fix(ui): keep latest issue document revision current (#3342)

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies.
> - Board users and agents collaborate on issue-scoped documents such as
plans and revisions need to be trustworthy because they are the audit
trail for those artifacts.
> - The issue document UI now supports revision history and restore, so
the UI has to distinguish the current revision from historical revisions
correctly even while multiple queries are refreshing.
> - In `PAPA-72`, the newest content could appear under an older
revision label because the current document snapshot and the
revision-history query could temporarily disagree after an edit.
> - That made the UI treat the newest revision like a historical restore
target, which is the opposite of the intended behavior.
> - This pull request derives one authoritative revision view from both
sources, sorts revisions newest-first, and keeps the freshest revision
marked current.
> - The benefit is that revision history stays stable and trustworthy
immediately after edits instead of briefly presenting the newest content
as an older revision.

## What Changed

- Added a `document-revisions` helper that merges the current document
snapshot with fetched revision history into one normalized revision
state.
- Updated `IssueDocumentsSection` to render from that normalized state
instead of trusting either query in isolation.
- Added focused tests covering the current-revision selection and
ordering behavior.

## Verification

- `pnpm -r typecheck`
- `pnpm build`
- Targeted revision tests passed locally.
- Manual reviewer check:
  - Open an issue document with revision history.
  - Edit and save the document.
  - Immediately open the revision selector.
- Confirm the newest revision remains marked current and older revisions
remain the restore targets.

## Risks

- Low risk. The change is isolated to issue document revision
presentation in the UI.
- Main risk is merging the current snapshot with fetched history
incorrectly for edge cases, which is why the helper has focused unit
coverage.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [ ] 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

ui/src/lib/document-revisions.test.ts

@@ -0,0 +1,95 @@
+import type { DocumentRevision, IssueDocument } from "@paperclipai/shared";
+import { describe, expect, it } from "vitest";
+import { deriveDocumentRevisionState } from "./document-revisions";
+
+function createDocument(overrides: Partial<IssueDocument> = {}): IssueDocument {
+  return {
+    id: "document-1",
+    companyId: "company-1",
+    issueId: "issue-1",
+    key: "plan",
+    title: "Plan",
+    format: "markdown",
+    body: "# Current plan",
+    latestRevisionId: "revision-2",
+    latestRevisionNumber: 2,
+    createdByAgentId: "agent-1",
+    createdByUserId: null,
+    updatedByAgentId: "agent-1",
+    updatedByUserId: null,
+    createdAt: new Date("2026-04-10T15:00:00.000Z"),
+    updatedAt: new Date("2026-04-10T16:00:00.000Z"),
+    ...overrides,
+  };
+}
+
+function createRevision(overrides: Partial<DocumentRevision> = {}): DocumentRevision {
+  return {
+    id: "revision-1",
+    companyId: "company-1",
+    documentId: "document-1",
+    issueId: "issue-1",
+    key: "plan",
+    revisionNumber: 1,
+    title: "Plan",
+    format: "markdown",
+    body: "# Revision body",
+    changeSummary: null,
+    createdByAgentId: "agent-1",
+    createdByUserId: null,
+    createdAt: new Date("2026-04-10T15:00:00.000Z"),
+    ...overrides,
+  };
+}
+
+describe("deriveDocumentRevisionState", () => {
+  it("falls back to a synthetic current revision when no revision history has been fetched yet", () => {
+    const state = deriveDocumentRevisionState(createDocument({
+      latestRevisionId: null,
+      latestRevisionNumber: 0,
+      body: "# Draft plan",
+    }), []);
+
+    expect(state.currentRevision.id).toBe("document-1-latest");
+    expect(state.currentRevision.body).toBe("# Draft plan");
+    expect(state.revisions.map((revision) => revision.id)).toEqual(["document-1-latest"]);
+  });
+
+  it("sorts fetched revisions newest-first even when the API payload is out of order", () => {
+    const state = deriveDocumentRevisionState(createDocument(), [
+      createRevision({ id: "revision-1", revisionNumber: 1, createdAt: new Date("2026-04-10T15:00:00.000Z") }),
+      createRevision({ id: "revision-2", revisionNumber: 2, body: "# Current plan", createdAt: new Date("2026-04-10T16:00:00.000Z") }),
+    ]);
+
+    expect(state.currentRevision.id).toBe("revision-2");
+    expect(state.revisions.map((revision) => revision.id)).toEqual(["revision-2", "revision-1"]);
+  });
+
+  it("keeps the latest document revision current when the revision history cache is stale", () => {
+    const state = deriveDocumentRevisionState(createDocument(), [
+      createRevision({ id: "revision-1", revisionNumber: 1, body: "# Original plan" }),
+    ]);
+
+    expect(state.currentRevision.id).toBe("revision-2");
+    expect(state.currentRevision.body).toBe("# Current plan");
+    expect(state.revisions.map((revision) => revision.id)).toEqual(["revision-2", "revision-1"]);
+  });
+
+  it("trusts the fetched revision history when it is newer than the document summary cache", () => {
+    const staleDocument = createDocument({
+      body: "# Original plan",
+      latestRevisionId: "revision-1",
+      latestRevisionNumber: 1,
+      updatedAt: new Date("2026-04-10T15:00:00.000Z"),
+    });
+
+    const state = deriveDocumentRevisionState(staleDocument, [
+      createRevision({ id: "revision-2", revisionNumber: 2, body: "# Current plan", createdAt: new Date("2026-04-10T16:00:00.000Z") }),
+      createRevision({ id: "revision-1", revisionNumber: 1, body: "# Original plan", createdAt: new Date("2026-04-10T15:00:00.000Z") }),
+    ]);
+
+    expect(state.currentRevision.id).toBe("revision-2");
+    expect(state.currentRevision.body).toBe("# Current plan");
+    expect(state.revisions.map((revision) => revision.id)).toEqual(["revision-2", "revision-1"]);
+  });
+});

ui/src/lib/document-revisions.ts

@@ -0,0 +1,72 @@
+import type { DocumentRevision, IssueDocument } from "@paperclipai/shared";
+
+type DocumentRevisionState = {
+  currentRevision: DocumentRevision;
+  revisions: DocumentRevision[];
+};
+
+function toTimestamp(value: Date | string | null | undefined) {
+  if (!value) return 0;
+  const timestamp = new Date(value).getTime();
+  return Number.isNaN(timestamp) ? 0 : timestamp;
+}
+
+function sortRevisionsDescending(revisions: DocumentRevision[]) {
+  return [...revisions].sort((a, b) => {
+    if (a.revisionNumber !== b.revisionNumber) {
+      return b.revisionNumber - a.revisionNumber;
+    }
+    const createdAtDelta = toTimestamp(b.createdAt) - toTimestamp(a.createdAt);
+    if (createdAtDelta !== 0) return createdAtDelta;
+    return b.id.localeCompare(a.id);
+  });
+}
+
+function createCurrentRevisionSnapshot(document: IssueDocument): DocumentRevision {
+  return {
+    id: document.latestRevisionId ?? `${document.id}-latest`,
+    companyId: document.companyId,
+    documentId: document.id,
+    issueId: document.issueId,
+    key: document.key,
+    revisionNumber: document.latestRevisionNumber,
+    title: document.title,
+    format: document.format,
+    body: document.body,
+    changeSummary: null,
+    createdByAgentId: document.updatedByAgentId ?? document.createdByAgentId,
+    createdByUserId: document.updatedByUserId ?? document.createdByUserId,
+    createdAt: document.updatedAt,
+  };
+}
+
+export function deriveDocumentRevisionState(
+  document: IssueDocument,
+  revisions: DocumentRevision[],
+): DocumentRevisionState {
+  const sortedRevisions = sortRevisionsDescending(revisions);
+  const currentSnapshot = createCurrentRevisionSnapshot(document);
+  const highestFetchedRevision = sortedRevisions[0] ?? null;
+  const documentAppearsStale = Boolean(
+    highestFetchedRevision && highestFetchedRevision.revisionNumber > document.latestRevisionNumber,
+  );
+
+  const currentRevision = documentAppearsStale
+    ? highestFetchedRevision!
+    : sortedRevisions.find((revision) => revision.id === document.latestRevisionId) ?? currentSnapshot;
+
+  const revisionsWithCurrent = sortRevisionsDescending([currentRevision, ...sortedRevisions]);
+  const dedupedRevisions: DocumentRevision[] = [];
+  const seenRevisionIds = new Set<string>();
+
+  for (const revision of revisionsWithCurrent) {
+    if (seenRevisionIds.has(revision.id)) continue;
+    seenRevisionIds.add(revision.id);
+    dedupedRevisions.push(revision);
+  }
+
+  return {
+    currentRevision,
+    revisions: dedupedRevisions,
+  };
+}