Add ordered sub-issue navigation (#5938)

## Thinking Path

> - Paperclip orchestrates AI-agent companies through company-scoped
issues, comments, and execution context.
> - The issue detail page is the board surface where operators and
agents inspect a task in its parent/child workflow.
> - Ordered sub-issues need a low-friction way to move through work
without returning to the parent list after every issue.
> - Existing issue detail navigation only covered sibling transitions
and did not continue into a parent issue's first ordered child.
> - This pull request adds ordered previous/next navigation for issue
detail views and extends it to continue from a parent or last sibling
into the first direct child.
> - The benefit is a smoother review/execution path through hierarchical
work while preserving hidden issue filtering and dependency-aware
ordering.

## What Changed

- Added `IssueSiblingNavigation` and route-state handling so issue
detail footers can link to previous/next ordered issues.
- Extended sub-issue ordering helpers to build navigation from siblings
plus direct children, including root-parent and
last-sibling-to-first-child cases.
- Added page, component, and library tests for ordered sibling
navigation, child fallback navigation, hidden issues, and link
rendering.
- Fixed the quicklook blur/click race Greptile found by deferring close
until after portaled link clicks can complete, with a regression test.
- Polished the navigation landmark label so it remains accurate when the
next target is a direct child rather than a sibling.

## Verification

- `pnpm exec vitest run src/components/IssueLinkQuicklook.test.tsx
src/lib/issue-detail-subissues.test.ts
src/components/IssueSiblingNavigation.test.tsx
src/pages/IssueDetail.test.tsx --config vitest.config.ts` from `ui/` -
31 tests passed.
- `pnpm --filter @paperclipai/ui typecheck` - passed.
- `git diff --check` - passed.
- GitHub PR checks on latest head `34046be2` - passed: Greptile Review,
verify, e2e, Canary Dry Run, policy, Snyk, and serialized server shards.
- Screenshots: not captured in this heartbeat; this PR is a draft and
the changed states are covered by focused component/page tests.

## Risks

- Low risk; this is a UI navigation addition with no database or API
contract changes.
- The main behavioral risk is navigation ordering drift if
`workflowSort` expectations change later.
- The IssueDetail navigation now waits for child issue loading, which
avoids stale child fallback links but can delay footer navigation
briefly while data loads.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected - check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- OpenAI Codex, GPT-5 coding agent with repository tool use and shell
execution.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

ui/src/components/IssueChatThread.test.tsx

@@ -346,6 +346,39 @@ describe("IssueChatThread", () => {
     });
   });
 
+  it("renders footer content inside the thread viewport before the bottom anchor", () => {
+    const root = createRoot(container);
+
+    act(() => {
+      root.render(
+        <MemoryRouter>
+          <IssueChatThread
+            comments={[]}
+            linkedRuns={[]}
+            timelineEvents={[]}
+            liveRuns={[]}
+            onAdd={async () => {}}
+            showComposer={false}
+            enableLiveTranscriptPolling={false}
+            footer={<div>Sibling footer</div>}
+          />
+        </MemoryRouter>,
+      );
+    });
+
+    const viewport = container.querySelector('[data-testid="thread-viewport"]');
+    const footer = container.querySelector('[data-testid="issue-chat-thread-footer"]');
+    expect(viewport).not.toBeNull();
+    expect(footer).not.toBeNull();
+    expect(footer?.textContent).toBe("Sibling footer");
+    expect(footer?.parentElement).toBe(viewport);
+    expect(footer?.nextElementSibling?.textContent).toBe("");
+
+    act(() => {
+      root.unmount();
+    });
+  });
+
   it("renders the composer in planning mode when the issue is in planning mode", () => {
     const root = createRoot(container);
 

ui/src/components/IssueChatThread.tsx

@@ -342,6 +342,7 @@ interface IssueChatThreadProps {
   showComposer?: boolean;
   showJumpToLatest?: boolean;
   emptyMessage?: string;
+  footer?: ReactNode;
   variant?: "full" | "embedded";
   enableLiveTranscriptPolling?: boolean;
   transcriptsByRunId?: ReadonlyMap<string, readonly IssueChatTranscriptEntry[]>;
@@ -3650,6 +3651,7 @@ export function IssueChatThread({
   showComposer = true,
   showJumpToLatest,
   emptyMessage,
+  footer,
   variant = "full",
   enableLiveTranscriptPolling = true,
   transcriptsByRunId,
@@ -4310,6 +4312,7 @@ export function IssueChatThread({
                   <IssueAssigneePausedNotice agent={assignedAgent} />
                 </div>
               ) : null}
+              {footer ? <div data-testid="issue-chat-thread-footer">{footer}</div> : null}
               <div ref={bottomAnchorRef} />
               {showComposer ? (
                 <div

ui/src/components/IssueLinkQuicklook.test.tsx

@@ -0,0 +1,136 @@
+// @vitest-environment jsdom
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { MemoryRouter } from "react-router-dom";
+import type { Issue } from "@paperclipai/shared";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { IssueLinkQuicklook } from "./IssueLinkQuicklook";
+
+const mockIssuesApiGet = vi.hoisted(() => vi.fn());
+
+vi.mock("@/api/issues", () => ({
+  issuesApi: {
+    get: mockIssuesApiGet,
+  },
+}));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+function createIssue(overrides: Partial<Issue> = {}): Issue {
+  return {
+    id: "issue-1",
+    identifier: "PAP-1",
+    companyId: "company-1",
+    projectId: null,
+    projectWorkspaceId: null,
+    goalId: null,
+    parentId: null,
+    title: "Quicklook title",
+    description: "Quicklook description",
+    status: "todo",
+    priority: "medium",
+    assigneeAgentId: null,
+    assigneeUserId: null,
+    createdByAgentId: null,
+    createdByUserId: null,
+    issueNumber: 1,
+    requestDepth: 0,
+    billingCode: null,
+    assigneeAdapterOverrides: null,
+    executionWorkspaceId: null,
+    executionWorkspacePreference: null,
+    executionWorkspaceSettings: null,
+    checkoutRunId: null,
+    executionRunId: null,
+    executionAgentNameKey: null,
+    executionLockedAt: null,
+    startedAt: null,
+    completedAt: null,
+    cancelledAt: null,
+    hiddenAt: null,
+    createdAt: new Date("2026-05-01T00:00:00.000Z"),
+    updatedAt: new Date("2026-05-01T00:00:00.000Z"),
+    labels: [],
+    labelIds: [],
+    myLastTouchAt: null,
+    lastExternalCommentAt: null,
+    isUnreadForMe: false,
+    workMode: "standard",
+    ...overrides,
+  };
+}
+
+describe("IssueLinkQuicklook", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+  let queryClient: QueryClient;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+    queryClient = new QueryClient({
+      defaultOptions: {
+        queries: {
+          retry: false,
+        },
+      },
+    });
+    mockIssuesApiGet.mockResolvedValue(createIssue());
+  });
+
+  afterEach(() => {
+    act(() => {
+      root.unmount();
+    });
+    queryClient.clear();
+    container.remove();
+    vi.useRealTimers();
+    vi.clearAllMocks();
+  });
+
+  it("keeps portaled quicklook links mounted until after blur click handling", () => {
+    const issue = createIssue();
+
+    act(() => {
+      root.render(
+        <QueryClientProvider client={queryClient}>
+          <MemoryRouter>
+            <IssueLinkQuicklook
+              issuePathId="PAP-1"
+              issuePrefetch={issue}
+              to="/companies/company-1/issues/PAP-1"
+            >
+              PAP-1
+            </IssueLinkQuicklook>
+          </MemoryRouter>
+        </QueryClientProvider>,
+      );
+    });
+
+    const trigger = container.querySelector("a") as HTMLAnchorElement | null;
+    expect(trigger).not.toBeNull();
+
+    act(() => {
+      trigger?.focus();
+    });
+
+    expect(document.body.textContent).toContain("Quicklook title");
+
+    act(() => {
+      trigger?.blur();
+    });
+
+    expect(document.body.textContent).toContain("Quicklook title");
+
+    act(() => {
+      vi.runOnlyPendingTimers();
+    });
+
+    expect(document.body.textContent).not.toContain("Quicklook title");
+  });
+});

ui/src/components/IssueLinkQuicklook.tsx

@@ -75,6 +75,8 @@ export const IssueLinkQuicklook = React.forwardRef<
     issuePathId: string;
     disableIssueQuicklook?: boolean;
     issuePrefetch?: Issue | null;
+    issueQuicklookSide?: React.ComponentProps<typeof PopoverContent>["side"];
+    issueQuicklookAlign?: React.ComponentProps<typeof PopoverContent>["align"];
   }
 >(function IssueLinkQuicklookImpl(
   {
@@ -85,10 +87,13 @@ export const IssueLinkQuicklook = React.forwardRef<
     state,
     disableIssueQuicklook = false,
     issuePrefetch = null,
+    issueQuicklookSide = "top",
+    issueQuicklookAlign = "start",
     onClick,
     onClickCapture,
     onMouseEnter,
     onFocus,
+    onBlur,
     onTouchStart,
     ...props
   },
@@ -119,8 +124,14 @@ export const IssueLinkQuicklook = React.forwardRef<
       }}
       onFocus={(event) => {
         handlePrefetch();
+        setOpen(true);
         onFocus?.(event);
       }}
+      onBlur={(event) => {
+        // Let clicks inside the portaled quicklook content finish before closing.
+        setTimeout(() => setOpen(false), 0);
+        onBlur?.(event);
+      }}
       onTouchStart={(event) => {
         handlePrefetch();
         onTouchStart?.(event);
@@ -157,8 +168,8 @@ export const IssueLinkQuicklook = React.forwardRef<
       </PopoverTrigger>
       <PopoverContent
         className="w-72 p-3"
-        side="top"
-        align="start"
+        side={issueQuicklookSide}
+        align={issueQuicklookAlign}
         onMouseEnter={() => setOpen(true)}
         onMouseLeave={() => setOpen(false)}
         onOpenAutoFocus={(event) => event.preventDefault()}

ui/src/components/IssueSiblingNavigation.test.tsx

@@ -0,0 +1,130 @@
+// @vitest-environment jsdom
+
+import { act, type AnchorHTMLAttributes, type ReactNode } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import type { Issue } from "@paperclipai/shared";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { IssueSiblingNavigation } from "./IssueSiblingNavigation";
+
+vi.mock("@/lib/router", () => ({
+  Link: ({
+    children,
+    to,
+    issueQuicklookAlign,
+    issueQuicklookSide,
+    issuePrefetch: _issuePrefetch,
+    state: _state,
+    ...props
+  }: AnchorHTMLAttributes<HTMLAnchorElement> & {
+    to: string;
+    issueQuicklookAlign?: string;
+    issueQuicklookSide?: string;
+    issuePrefetch?: unknown;
+    state?: unknown;
+    children?: ReactNode;
+  }) => (
+    <a
+      href={to}
+      data-quicklook-align={issueQuicklookAlign}
+      data-quicklook-side={issueQuicklookSide}
+      {...props}
+    >
+      {children}
+    </a>
+  ),
+}));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+function issue(id: string, overrides: Partial<Issue> = {}): Issue {
+  return {
+    id,
+    identifier: `PAP-${id}`,
+    title: `Sibling ${id}`,
+    status: "todo",
+    blockerAttention: null,
+    createdAt: new Date("2026-05-01T00:00:00.000Z"),
+    updatedAt: new Date("2026-05-01T00:00:00.000Z"),
+    ...overrides,
+  } as Issue;
+}
+
+let root: Root | null = null;
+let container: HTMLDivElement | null = null;
+
+afterEach(() => {
+  if (root) {
+    act(() => root?.unmount());
+  }
+  root = null;
+  container?.remove();
+  container = null;
+});
+
+function render(node: ReactNode) {
+  container = document.createElement("div");
+  document.body.appendChild(container);
+  root = createRoot(container);
+  act(() => root?.render(node));
+  return container;
+}
+
+describe("IssueSiblingNavigation", () => {
+  it("renders the locked card anatomy for previous and next siblings", () => {
+    const node = render(
+      <IssueSiblingNavigation
+        navigation={{
+          previous: issue("1", { title: "Previous sibling title" }),
+          next: issue("3", { title: "Next sibling title" }),
+          currentIndex: 1,
+          totalCount: 3,
+        }}
+      />,
+    );
+
+    const nav = node.querySelector("nav");
+    expect(nav?.getAttribute("aria-label")).toBe("Sub-issue navigation");
+    expect(nav?.className).toContain("sm:grid-cols-2");
+    expect(nav?.className).not.toContain("border-t");
+
+    const links = Array.from(node.querySelectorAll("a"));
+    expect(links).toHaveLength(2);
+    expect(links[0].textContent).toContain("Previous");
+    expect(links[0].textContent).toContain("PAP-1");
+    expect(links[0].textContent).toContain("Previous sibling title");
+    expect(links[0].getAttribute("aria-label")).toBe("Previous sub-issue: PAP-1 - Previous sibling title");
+    expect(links[0].getAttribute("data-quicklook-align")).toBe("start");
+
+    expect(links[1].textContent).toContain("Next");
+    expect(links[1].textContent).toContain("PAP-3");
+    expect(links[1].textContent).toContain("Next sibling title");
+    expect(links[1].getAttribute("aria-label")).toBe("Next sub-issue: PAP-3 - Next sibling title");
+    expect(links[1].getAttribute("data-quicklook-align")).toBe("end");
+    expect(links[1].className).toContain("sm:text-right");
+
+    expect(links[0].className).toContain("rounded-lg");
+    expect(links[0].className).toContain("hover:bg-accent/50");
+    expect(links[0].className).toContain("focus-visible:ring-[3px]");
+    expect(node.querySelector(".truncate")?.textContent).toBe("Previous sibling title");
+  });
+
+  it("keeps a lone next card in the right desktop column", () => {
+    const node = render(
+      <IssueSiblingNavigation
+        navigation={{
+          previous: null,
+          next: issue("2"),
+          currentIndex: 0,
+          totalCount: 2,
+        }}
+      />,
+    );
+
+    const links = Array.from(node.querySelectorAll("a"));
+    expect(links).toHaveLength(1);
+    expect(links[0].textContent).toContain("Next");
+    expect(links[0].className).toContain("sm:col-start-2");
+    expect(node.textContent).not.toContain("Previous");
+  });
+});

ui/src/components/IssueSiblingNavigation.tsx

@@ -0,0 +1,90 @@
+import { ChevronLeft, ChevronRight } from "lucide-react";
+import type { Issue } from "@paperclipai/shared";
+import type { IssueSiblingNavigation as IssueSiblingNavigationState } from "@/lib/issue-detail-subissues";
+import { createIssueDetailPath, withIssueDetailHeaderSeed } from "@/lib/issueDetailBreadcrumb";
+import { cn } from "@/lib/utils";
+import { Link } from "@/lib/router";
+import { StatusIcon } from "./StatusIcon";
+
+type IssueSiblingNavigationProps = {
+  navigation: IssueSiblingNavigationState | null;
+  linkState?: unknown;
+};
+
+export function IssueSiblingNavigation({ navigation, linkState }: IssueSiblingNavigationProps) {
+  if (!navigation) return null;
+
+  return (
+    <nav
+      aria-label="Sub-issue navigation"
+      className="mt-4 flex flex-col gap-3 sm:mt-6 sm:grid sm:grid-cols-2"
+    >
+      {navigation.previous ? (
+        <SiblingLink direction="previous" issue={navigation.previous} linkState={linkState} />
+      ) : null}
+      {navigation.next ? (
+        <SiblingLink
+          direction="next"
+          issue={navigation.next}
+          linkState={linkState}
+          className={!navigation.previous ? "sm:col-start-2" : undefined}
+        />
+      ) : null}
+    </nav>
+  );
+}
+
+function SiblingLink({
+  direction,
+  issue,
+  linkState,
+  className,
+}: {
+  direction: "previous" | "next";
+  issue: Issue;
+  linkState?: unknown;
+  className?: string;
+}) {
+  const issuePathId = issue.identifier ?? issue.id;
+  const label = direction === "previous" ? "Previous" : "Next";
+  const ariaDirection = direction === "previous" ? "Previous sub-issue" : "Next sub-issue";
+  const identifier = issue.identifier ?? issue.id.slice(0, 8);
+  const Icon = direction === "previous" ? ChevronLeft : ChevronRight;
+
+  return (
+    <Link
+      to={createIssueDetailPath(issuePathId)}
+      state={withIssueDetailHeaderSeed(linkState, issue)}
+      issuePrefetch={issue}
+      issueQuicklookSide="top"
+      issueQuicklookAlign={direction === "previous" ? "start" : "end"}
+      aria-label={`${ariaDirection}: ${identifier} - ${issue.title}`}
+      className={cn(
+        "group min-w-0 rounded-lg border border-border bg-card px-3 py-2.5 text-left no-underline transition-colors hover:bg-accent/50 focus-visible:outline-none focus-visible:ring-[3px] focus-visible:ring-ring",
+        direction === "next" && "sm:text-right",
+        className,
+      )}
+    >
+      <div className="min-w-0 space-y-1.5">
+        <div className={cn(
+          "flex items-center gap-1.5 text-xs text-muted-foreground transition-colors group-hover:text-foreground",
+          direction === "next" && "sm:justify-end",
+        )}>
+          {direction === "previous" ? <Icon className="h-3.5 w-3.5 shrink-0" /> : null}
+          <span>{label}</span>
+          {direction === "next" ? <Icon className="h-3.5 w-3.5 shrink-0" /> : null}
+        </div>
+        <div className={cn(
+          "flex min-w-0 items-center gap-1.5 text-xs font-mono text-muted-foreground transition-colors group-hover:text-foreground",
+          direction === "next" && "sm:justify-end",
+        )}>
+          <StatusIcon status={issue.status} blockerAttention={issue.blockerAttention} />
+          <span className="shrink-0">{identifier}</span>
+        </div>
+        <div className="truncate text-sm text-foreground">
+          {issue.title}
+        </div>
+      </div>
+    </Link>
+  );
+}