@cat-factory/app 0.163.0 → 0.165.0

package/README.md

@@ -77,7 +77,10 @@ example ships in [`deploy/frontend`](../../deploy/frontend) (the `acme:security`
   structure, dependencies, model + fragment picker, live execution, and linked
   docs/issues/scenarios. Decisions resolve via `DecisionModal`.
 - **Pipeline builder** (`components/pipeline`) — assemble/edit agent chains and
-  watch `PipelineProgress`.
+  watch `PipelineProgress`. `PipelinePicker` (+ its `PipelinePreview` pane) is the
+  single way a pipeline is chosen anywhere — add-task, run settings, the recurring
+  schedule, the focus view's Run menu — so every surface explains a pipeline by the
+  ordered steps it will run rather than by its name alone.
 - **Integrations** — modals/panels for `github` (the source-control panel, shared
   by every VCS provider), `vcs` (the GitLab personal-access-token connect),
   `bootstrap`, `documents`, `tasks`, `requirements` (review), `scenarios`

package/app/components/board/RecurringPipelineModal.vue

@@ -70,17 +70,7 @@ function defaultRecurrence(): Recurrence {
 const selectablePipelines = computed(() =>
   pipelines.pipelines.filter((p) => pipelineAllowedForSchedule(p, frame.value, board.blocks)),
 )
-const pipelineMenu = computed(() => [
-  selectablePipelines.value.map((p) => ({
-    label: p.name,
-    icon: 'i-lucide-workflow',
-    onSelect: () => (pipelineId.value = p.id),
-  })),
-])
 const selectedPipeline = computed(() => pipelines.getPipeline(pipelineId.value))
-const selectedPipelineLabel = computed(
-  () => selectedPipeline.value?.name ?? t('board.recurring.pickPipeline'),
-)
 
 // Infer the template from the picked pipeline so the backend seeds the right block
 // description (and so we know to show the tracker config).
@@ -269,19 +259,16 @@ async function add() {
           />
         </UFormField>
 
+        <!-- The rich picker, not a name-only menu: which steps a schedule will run unattended,
+             every time it fires, is exactly what the person setting it up needs to see. A schedule
+             must name a pipeline, so there is no "none" row. -->
         <UFormField :label="t('board.recurring.pipeline')" required>
-          <UDropdownMenu :items="pipelineMenu" class="w-full">
-            <UButton
-              color="neutral"
-              variant="subtle"
-              size="sm"
-              icon="i-lucide-workflow"
-              trailing-icon="i-lucide-chevron-down"
-              class="w-full justify-between"
-            >
-              {{ selectedPipelineLabel }}
-            </UButton>
-          </UDropdownMenu>
+          <PipelinePicker
+            v-model="pipelineId"
+            :options="selectablePipelines"
+            :placeholder="t('board.recurring.pickPipeline')"
+            trigger-class="w-full justify-between"
+          />
         </UFormField>
 
         <UFormField :label="t('board.recurring.prompt')">

package/app/components/focus/BlockFocusView.vue

@@ -31,17 +31,19 @@ const deps = computed(() =>
 // Hide UI-testing pipelines when this block's frame has no UI to exercise, `'recurring'`-only
 // pipelines (a manual run of one is refused server-side), and — for a `document` task — every
 // non-document pipeline (per the `purpose` classifier) — see the backend gate.
-const runMenu = computed(() => {
+const runOptions = computed(() => {
   const frame = block.value ? board.serviceOf(block.value) : undefined
-  return pipelines.pipelines
-    .filter((p) => pipelineAllowedForManualStart(p, frame, board.blocks, block.value?.taskType))
-    .map((p) => ({
-      label: p.name,
-      icon: 'i-lucide-play',
-      onSelect: () => block.value && execution.start(block.value.id, p),
-    }))
+  return pipelines.pipelines.filter((p) =>
+    pipelineAllowedForManualStart(p, frame, board.blocks, block.value?.taskType),
+  )
 })
 
+/** Start the picked pipeline immediately — the Run menu chooses an ACTION, it stores no default. */
+function runPipeline(id: string) {
+  const pipeline = pipelines.getPipeline(id)
+  if (pipeline && block.value) void execution.start(block.value.id, pipeline)
+}
+
 function close() {
   ui.focus(null)
 }
@@ -97,17 +99,21 @@ function openApprovalFor(approvalId: string) {
         {{ statusMeta.label }}
       </UBadge>
       <div class="ms-auto flex items-center gap-2">
-        <UDropdownMenu :items="runMenu">
-          <UButton
-            color="primary"
-            variant="soft"
-            size="sm"
-            icon="i-lucide-play"
-            trailing-icon="i-lucide-chevron-down"
-          >
-            {{ instance ? t('focus.rerunPipeline') : t('focus.runPipeline') }}
-          </UButton>
-        </UDropdownMenu>
+        <!-- The rich picker rather than a list of names: the run starts the moment a row is
+             clicked, so the preview is the only chance to see which agents it will run. -->
+        <PipelinePicker model-value="" :options="runOptions" @update:model-value="runPipeline">
+          <template #trigger>
+            <UButton
+              color="primary"
+              variant="soft"
+              size="sm"
+              icon="i-lucide-play"
+              trailing-icon="i-lucide-chevron-down"
+            >
+              {{ instance ? t('focus.rerunPipeline') : t('focus.runPipeline') }}
+            </UButton>
+          </template>
+        </PipelinePicker>
         <IconButton
           icon="i-lucide-x"
           color="neutral"

package/app/components/pipeline/PipelinePicker.vue

@@ -1,25 +1,36 @@
 <script setup lang="ts">
-// The rich pipeline picker used wherever a pipeline is chosen (add-task modal, inspector run
-// settings). A master–detail popover: the left column lists the selectable pipelines (plus a
-// "none / choose at run time" row), and hovering a row reveals that pipeline's full preview — its
-// description + the ordered agent steps — in the right column, so a user sees exactly what a
-// pipeline does before picking it. The trigger is customizable via the `#trigger` slot (the
-// inspector uses a bare icon button; the modal a full-width labelled one).
+// The rich pipeline picker used wherever a pipeline is chosen — as a stored default (add-task
+// modal, inspector run settings, the recurring-schedule modal) or as an immediate action (the
+// focus view's Run menu). A master–detail popover: the left column lists the selectable pipelines
+// (plus an optional "none / choose at run time" row), and hovering a row reveals that pipeline's
+// full preview — its description and every step it will run, in order — in the right column, so a
+// user sees exactly what a pipeline does before picking it. The trigger is customizable via the
+// `#trigger` slot (the inspector uses a bare icon button; the modal a full-width labelled one).
 import { computed, ref } from 'vue'
 import type { Pipeline } from '~/types/domain'
 
 const props = withDefaults(
   defineProps<{
-    /** Selected pipeline id, or '' for the "none" option. */
+    /** Selected pipeline id, or '' for none. An action-mode caller passes a constant ''. */
     modelValue: string
     /** The pipelines offered (already filtered for the surface, e.g. manual-start allowed). */
     options: Pipeline[]
-    /** Label for the "none" row (e.g. "Choose at run time" / "No default"). */
-    noneLabel: string
+    /**
+     * Label for the "none" row (e.g. "Choose at run time" / "No default"). Omit where picking
+     * nothing is not a valid outcome — a schedule needs a pipeline, and a Run menu acts on the
+     * chosen row — and the row is left out entirely.
+     */
+    noneLabel?: string
+    /**
+     * Default-trigger text while nothing is selected. Defaults to {@link noneLabel}, which reads
+     * correctly when the "none" row IS the empty state; a surface without that row supplies its
+     * own prompt ("Pick a pipeline").
+     */
+    placeholder?: string
     /** Extra classes for the default trigger button (e.g. full-width in the modal). */
     triggerClass?: string
   }>(),
-  { triggerClass: '' },
+  { noneLabel: undefined, placeholder: undefined, triggerClass: '' },
 )
 
 const emit = defineEmits<{ 'update:modelValue': [string] }>()
@@ -31,7 +42,9 @@ const open = ref(false)
 const hoverId = ref<string | undefined>(undefined)
 
 const selected = computed(() => props.options.find((p) => p.id === props.modelValue))
-const triggerLabel = computed(() => selected.value?.name ?? props.noneLabel)
+const triggerLabel = computed(
+  () => selected.value?.name ?? props.placeholder ?? props.noneLabel ?? '',
+)
 
 /** The pipeline the right pane previews: the hovered row, else the current selection. */
 const previewPipeline = computed<Pipeline | null>(() => {
@@ -39,6 +52,17 @@ const previewPipeline = computed<Pipeline | null>(() => {
   return id ? (props.options.find((p) => p.id === id) ?? null) : null
 })
 
+/**
+ * With no pipeline to preview the pane explains WHY it's empty, and the two reasons differ: the
+ * "none" row is a real choice worth describing, while a picker without one is simply waiting for
+ * a hover. Sharing one hint would tell a Run menu it has no default pipeline, which is nonsense.
+ */
+const emptyHint = computed(() =>
+  props.noneLabel !== undefined && (hoverId.value ?? props.modelValue) === ''
+    ? t('pipeline.picker.noneHint')
+    : t('pipeline.picker.hoverHint'),
+)
+
 function choose(id: string) {
   emit('update:modelValue', id)
   open.value = false
@@ -63,13 +87,13 @@ function choose(id: string) {
 
     <template #content>
       <div
-        class="flex max-h-[24rem] w-[min(44rem,94vw)]"
+        class="flex max-h-[28rem] w-[min(44rem,94vw)]"
         data-testid="pipeline-picker-panel"
         @mouseleave="hoverId = undefined"
       >
         <!-- left: selectable options -->
         <ul class="w-1/2 shrink-0 overflow-y-auto border-e border-slate-800 p-1">
-          <li>
+          <li v-if="noneLabel !== undefined">
             <button
               type="button"
               class="flex w-full items-center gap-2 rounded px-2 py-1.5 text-start text-sm hover:bg-slate-800/60"
@@ -110,9 +134,7 @@ function choose(id: string) {
         <!-- right: preview of the hovered (or selected) pipeline -->
         <div class="w-1/2 overflow-y-auto p-3">
           <PipelinePreview v-if="previewPipeline" :pipeline="previewPipeline" />
-          <div v-else class="text-[12px] leading-snug text-slate-500">
-            {{ t('pipeline.picker.noneHint') }}
-          </div>
+          <div v-else class="text-[12px] leading-snug text-slate-500">{{ emptyHint }}</div>
         </div>
       </div>
     </template>

package/app/components/pipeline/PipelinePreview.vue

@@ -1,17 +1,28 @@
 <script setup lang="ts">
 // A compact, read-only summary of a pipeline: its name, prose description (when authored), and the
-// ordered list of enabled agent steps rendered as icon+label chips (a human-gated step is flagged).
-// Shared by the pipeline pickers' hover preview so "what a pipeline consists of" is explained the
-// same way everywhere. Resolves each step's display metadata through the single `agentKindMeta`
-// path (via <AgentKindIcon>), so a system/custom kind can never blow up the renderer.
+// ordered list of steps it will actually run — each a numbered row carrying the agent's icon, label
+// and catalog description, with the human approval gates flagged. The FULL list, not a step count:
+// "what does this pipeline actually do" is the only question a picker's preview pane exists to
+// answer, and a row of interchangeable chips answers just "how many". Shared by the pipeline
+// pickers everywhere a pipeline is chosen, so the explanation is identical on every surface.
+// Resolves each step's display metadata through the single `agentKindMeta` path (via
+// <AgentKindIcon> and {@link stepDescription}), so a system/custom kind can never blow up the
+// renderer.
 import { computed } from 'vue'
 import type { Pipeline } from '~/types/domain'
-import { pipelineDisplaySteps } from '~/utils/pipeline'
+import { agentKindMeta } from '~/utils/catalog'
+import { pipelineDisplaySteps, pipelineGateCount } from '~/utils/pipeline'
 
 const props = defineProps<{ pipeline: Pipeline }>()
 const { t } = useI18n()
 
 const steps = computed(() => pipelineDisplaySteps(props.pipeline))
+const gateCount = computed(() => pipelineGateCount(props.pipeline))
+
+/** What the agent at this step does — the same catalog prose the palette and step tooltips use. */
+function stepDescription(kind: string): string {
+  return agentKindMeta(kind).description
+}
 </script>
 
 <template>
@@ -24,26 +35,57 @@ const steps = computed(() => pipelineDisplaySteps(props.pipeline))
     >
       {{ pipeline.description }}
     </p>
-    <div>
-      <div class="mb-1 flex items-center gap-1 text-[10px] uppercase tracking-wide text-slate-500">
+
+    <div
+      class="flex flex-wrap items-center gap-x-3 gap-y-1 text-[10px] uppercase tracking-wide text-slate-500"
+    >
+      <span class="inline-flex items-center gap-1">
         <UIcon name="i-lucide-workflow" class="h-3 w-3" />
         {{ t('pipeline.preview.stepCount', { count: steps.length }, steps.length) }}
-      </div>
-      <ol class="flex flex-wrap items-center gap-1">
-        <li
-          v-for="(s, i) in steps"
-          :key="i"
-          class="inline-flex items-center gap-1 rounded bg-slate-800/70 px-1.5 py-0.5"
-        >
-          <AgentKindIcon :kind="s.kind" show-label icon-class="h-3.5 w-3.5" />
-          <UIcon
-            v-if="s.gated"
-            name="i-lucide-shield-check"
-            class="h-3 w-3 text-amber-400"
-            :title="t('pipeline.preview.gated')"
-          />
-        </li>
-      </ol>
+      </span>
+      <!-- Gates are the reason a run stops for a human, so they earn a headline of their own
+           rather than only the per-step marker below. -->
+      <span v-if="gateCount" class="inline-flex items-center gap-1 text-amber-500">
+        <UIcon name="i-lucide-shield-check" class="h-3 w-3" />
+        {{ t('pipeline.preview.gateCount', { count: gateCount }, gateCount) }}
+      </span>
     </div>
+
+    <!-- The ordered steps. The number column doubles as the flow connector (a rule drawn between
+         consecutive numbers), so the list reads as a sequence rather than an unordered set. -->
+    <ol>
+      <li
+        v-for="(s, i) in steps"
+        :key="i"
+        class="flex gap-2"
+        data-testid="pipeline-preview-step"
+        :data-step-kind="s.kind"
+      >
+        <div class="flex flex-col items-center">
+          <span
+            class="flex h-4 w-4 shrink-0 items-center justify-center rounded-full bg-slate-800 font-mono text-[9px] tabular-nums text-slate-400"
+          >
+            {{ i + 1 }}
+          </span>
+          <span v-if="i < steps.length - 1" class="w-px flex-1 bg-slate-800" />
+        </div>
+        <div class="min-w-0 flex-1 pb-2">
+          <div class="flex items-center gap-1">
+            <AgentKindIcon :kind="s.kind" show-label icon-class="h-3.5 w-3.5" />
+            <UIcon
+              v-if="s.gated"
+              name="i-lucide-shield-check"
+              class="h-3 w-3 shrink-0 text-amber-400"
+              :title="t('pipeline.preview.gated')"
+            />
+          </div>
+          <!-- Clamped: the catalog prose runs long for some kinds, and <AgentKindIcon> already
+               carries the full text in its hover tooltip. -->
+          <p class="line-clamp-2 text-[11px] leading-snug text-slate-500">
+            {{ stepDescription(s.kind) }}
+          </p>
+        </div>
+      </li>
+    </ol>
   </div>
 </template>

package/app/components/requirements/RequirementsReviewWindow.logic.spec.ts

@@ -0,0 +1,145 @@
+import { describe, it, expect } from 'vitest'
+import {
+  findingAttention,
+  orderFindings,
+  reconcileFindingOrder,
+  type FindingRecommendationState,
+  type OrderedFinding,
+} from './RequirementsReviewWindow.logic'
+import type { RequirementReviewItem } from '~/types/requirements'
+
+/**
+ * The findings list's floating order. The point of the feature is that a human working a long
+ * review never has to hunt for what is still on them, so these pin the bucketing (including the
+ * cases where the recommendation state disagrees with the finding's own status), the tie-breaking
+ * that keeps the sort stable, and the pinning rule that stops the list re-sorting under a cursor
+ * without ever letting a stale pin hide a newly-raised finding.
+ */
+const NO_REC: FindingRecommendationState = { pending: false, ready: false }
+
+const item = (
+  id: string,
+  status: RequirementReviewItem['status'],
+  severity: RequirementReviewItem['severity'] = 'medium',
+): RequirementReviewItem => ({
+  id,
+  category: 'question',
+  severity,
+  title: id,
+  detail: `detail for ${id}`,
+  status,
+  reply: null,
+  createdAt: 0,
+  updatedAt: 0,
+})
+
+const order = (
+  items: RequirementReviewItem[],
+  recs: Record<string, FindingRecommendationState> = {},
+) => orderFindings(items, (i) => recs[i.id] ?? NO_REC)
+
+describe('findingAttention', () => {
+  it('puts an unanswered finding on the human', () => {
+    expect(findingAttention(item('a', 'open'), NO_REC)).toBe('action')
+  })
+
+  it('settles a finding the human already reacted to', () => {
+    expect(findingAttention(item('a', 'answered'), NO_REC)).toBe('settled')
+    expect(findingAttention(item('a', 'dismissed'), NO_REC)).toBe('settled')
+    expect(findingAttention(item('a', 'resolved'), NO_REC)).toBe('settled')
+  })
+
+  it('parks a finding whose suggestion is still being generated', () => {
+    expect(
+      findingAttention(item('a', 'recommend_requested'), { pending: true, ready: false }),
+    ).toBe('waiting')
+    // Even one the human never settled: there is nothing to react to until the Writer lands.
+    expect(findingAttention(item('a', 'open'), { pending: true, ready: false })).toBe('waiting')
+  })
+
+  it('returns a finding to the human the moment its suggestion is ready to accept or reject', () => {
+    expect(
+      findingAttention(item('a', 'recommend_requested'), { pending: false, ready: true }),
+    ).toBe('action')
+    // A ready suggestion outranks even an answer already recorded — accept/reject is still owed.
+    expect(findingAttention(item('a', 'answered'), { pending: false, ready: true })).toBe('action')
+  })
+
+  it('returns a recommend-requested finding with nothing in flight to the human', () => {
+    // The suggestion was rejected / never landed: nothing more is coming, so it is back on them.
+    expect(findingAttention(item('a', 'recommend_requested'), NO_REC)).toBe('action')
+  })
+})
+
+describe('orderFindings', () => {
+  it('floats what needs a reaction above what is waiting, above what is handled', () => {
+    const items = [
+      item('handled', 'answered'),
+      item('waiting', 'recommend_requested'),
+      item('needs-me', 'open'),
+    ]
+    expect(
+      order(items, { waiting: { pending: true, ready: false } }).map((entry) => entry.id),
+    ).toEqual(['needs-me', 'waiting', 'handled'])
+  })
+
+  it('keeps severity as the order within a bucket', () => {
+    const items = [item('low', 'open', 'low'), item('high', 'open', 'high'), item('mid', 'open')]
+    expect(order(items).map((entry) => entry.id)).toEqual(['high', 'mid', 'low'])
+  })
+
+  it('breaks ties on the reviewer ordering, so the sort is stable', () => {
+    const items = [item('first', 'open'), item('second', 'open'), item('third', 'open')]
+    expect(order(items).map((entry) => entry.id)).toEqual(['first', 'second', 'third'])
+  })
+
+  it('outranks severity by attention, so a low open finding beats a high handled one', () => {
+    const items = [item('high-handled', 'dismissed', 'high'), item('low-open', 'open', 'low')]
+    expect(order(items).map((entry) => entry.id)).toEqual(['low-open', 'high-handled'])
+  })
+
+  it('tags each entry with the bucket its position came from', () => {
+    const items = [item('a', 'open'), item('b', 'dismissed')]
+    expect(order(items)).toEqual([
+      { id: 'a', attention: 'action' },
+      { id: 'b', attention: 'settled' },
+    ])
+  })
+
+  it('handles an empty review', () => {
+    expect(order([])).toEqual([])
+  })
+})
+
+describe('reconcileFindingOrder', () => {
+  const desired: OrderedFinding[] = [
+    { id: 'a', attention: 'action' },
+    { id: 'b', attention: 'settled' },
+  ]
+
+  it('falls back to the computed order when nothing is pinned', () => {
+    expect(reconcileFindingOrder(desired, null)).toEqual(desired)
+  })
+
+  it('holds the pinned order while it covers the same findings', () => {
+    // `b` has since been answered and would now sink, but the pin keeps the list still.
+    const pinned: OrderedFinding[] = [
+      { id: 'b', attention: 'action' },
+      { id: 'a', attention: 'action' },
+    ]
+    expect(reconcileFindingOrder(desired, pinned)).toBe(pinned)
+  })
+
+  it('drops a pin that no longer covers every finding, so a new one can never be hidden', () => {
+    const pinned: OrderedFinding[] = [{ id: 'a', attention: 'action' }]
+    expect(reconcileFindingOrder(desired, pinned)).toEqual(desired)
+  })
+
+  it('drops a pin naming a finding the review no longer has', () => {
+    const pinned: OrderedFinding[] = [
+      { id: 'a', attention: 'action' },
+      { id: 'gone', attention: 'action' },
+    ]
+    expect(reconcileFindingOrder(desired, pinned)).toEqual(desired)
+  })
+})

package/app/components/requirements/RequirementsReviewWindow.logic.ts

@@ -0,0 +1,105 @@
+// Pure ordering for the requirements-review window's findings list.
+//
+// A reviewer pass raises its findings in whatever order it produced them, and the human then
+// works down the list answering, dismissing or handing findings to the Requirement Writer. A
+// finding they have dealt with keeps its slot, so on a long review (and on every re-review, which
+// re-raises what is still unresolved alongside what is new) the ones still waiting on a reaction
+// end up scattered between settled ones. This floats what still needs the human to the top and
+// sinks what is already handled, so "what is left for me?" is answered by looking at the top of
+// the list instead of scrolling it end to end.
+//
+// Kept out of the SFC so the bucketing, the comparator and the pinning rule are unit-testable
+// without mounting Nuxt.
+import type { RequirementReviewItem, ReviewItemSeverity } from '~/types/requirements'
+
+/**
+ * How much of the human's attention a finding still wants.
+ * - `action` — the ball is in THEIR court: an unanswered finding, or a Writer suggestion sitting
+ *   there awaiting accept/reject.
+ * - `waiting` — the ball is in the MACHINE's court: the Requirement Writer is still producing a
+ *   suggestion for this finding, so there is nothing to react to yet.
+ * - `settled` — answered, dismissed or resolved; nothing further is owed per-finding (the review
+ *   as a whole still needs the incorporate/proceed decision, which lives in the action rail).
+ */
+export type FindingAttention = 'action' | 'waiting' | 'settled'
+
+/** What the review's recommendation collection currently holds for one finding. */
+export interface FindingRecommendationState {
+  /** A requested suggestion is still being generated by the Writer. */
+  pending: boolean
+  /** A generated suggestion is waiting on the human's accept/reject. */
+  ready: boolean
+}
+
+/** One finding in the rendered order, tagged with the bucket its position came from. */
+export interface OrderedFinding {
+  id: string
+  attention: FindingAttention
+}
+
+const ATTENTION_RANK: Record<FindingAttention, number> = { action: 0, waiting: 1, settled: 2 }
+const SEVERITY_RANK: Record<ReviewItemSeverity, number> = { high: 0, medium: 1, low: 2 }
+
+/**
+ * Which bucket a finding belongs in. The recommendation state OUTRANKS the finding's own status,
+ * because that is where the actionability actually moved: a finding parked in
+ * `recommend_requested` is the human's problem again the moment a suggestion lands (accept or
+ * reject), and is nobody's problem while the Writer is still thinking. A `recommend_requested`
+ * finding with NEITHER a pending nor a ready suggestion has had its recommendation declined or
+ * lost, so nothing more is coming and it is back on the human — the opposite of what its status
+ * alone would suggest.
+ */
+export function findingAttention(
+  item: Pick<RequirementReviewItem, 'status'>,
+  recommendation: FindingRecommendationState,
+): FindingAttention {
+  if (recommendation.ready) return 'action'
+  if (recommendation.pending) return 'waiting'
+  if (item.status === 'open' || item.status === 'recommend_requested') return 'action'
+  return 'settled'
+}
+
+/**
+ * The findings in the order the window should render them: unreacted-to first, then whatever the
+ * Writer is still working on, then everything already handled. Severity stays the secondary key
+ * (the order the window has always used within a bucket), and the reviewer's own ordering breaks
+ * the remaining ties so the sort is total and stable.
+ */
+export function orderFindings(
+  items: readonly RequirementReviewItem[],
+  recommendationFor: (item: RequirementReviewItem) => FindingRecommendationState,
+): OrderedFinding[] {
+  return items
+    .map((item, index) => ({
+      id: item.id,
+      attention: findingAttention(item, recommendationFor(item)),
+      severity: item.severity,
+      index,
+    }))
+    .sort(
+      (a, b) =>
+        ATTENTION_RANK[a.attention] - ATTENTION_RANK[b.attention] ||
+        SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] ||
+        a.index - b.index,
+    )
+    .map(({ id, attention }) => ({ id, attention }))
+}
+
+/**
+ * Which order to actually render: the PINNED one while it still covers exactly the same findings,
+ * otherwise the freshly computed one.
+ *
+ * The window pins the order while the human is typing in a finding's box and re-pins once they
+ * leave it, because an answer auto-saves on blur: re-sorting at that exact moment would slide the
+ * card they just clicked into out from under the cursor. Pinning is only ever allowed to hold a
+ * position STALE, never to hide a finding — a reviewer pass that adds or drops findings therefore
+ * invalidates the pin outright rather than rendering a list missing the new ones.
+ */
+export function reconcileFindingOrder(
+  desired: readonly OrderedFinding[],
+  pinned: readonly OrderedFinding[] | null,
+): readonly OrderedFinding[] {
+  if (!pinned || pinned.length !== desired.length) return desired
+  const ids = new Set(desired.map((entry) => entry.id))
+  return pinned.every((entry) => ids.has(entry.id)) ? pinned : desired
+}