@@ -0,0 +1,14 @@
+---
+'@object-ui/plugin-detail': patch
+'@object-ui/plugin-kanban': patch
+---
+
+fix(ui): the stage path and the kanban lay a select's options out by their declared lifecycle `kind` (#26612)
+
+Clause-②: no
+Metadata-protocol: none
+
+A select option may declare `kind: 'open' | 'won' | 'lost'` (`SelectOption.kind` in `@objectstack/spec`). Two readers now follow it instead of the option order or the value's spelling.
+
+- **`record:path`.** Once the status field declares a kind on any option, an option without one reads as `open`, the spec's rule for an absent kind, and is never classified from a `closed_won` / `closed_lost` spelling. The stages are laid out by kind: the open options as the steps in their authored order, then every won option as the forward terminus, then the lost options apart from the rail. A lost option authored mid-list no longer pulls the options after it into the lost group. A field that declares no kind keeps the spelling fallback and its positional layout as before, and a dev build now warns once, naming the object, the field and the stages it guessed.
+- **Kanban.** Lanes the board derives from the lane field's options run open → won → lost when the field declares a kind, each class in its authored order, and every lost lane starts collapsed: a spine with its card count that the viewer can open. Authored `columns` and fields that declare no kind keep their order; the board guesses nothing from spelling.
@@ -0,0 +1,225 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * Once a field declares an option `kind`, the path is laid out by kind and
+ * nothing is guessed from spelling (objectstack#26612)
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * objectui#12907 taught `record:path` to read a declared `kind`, but it still
+ * (1) filled any option WITHOUT a kind from the `closed_won` / `closed_lost`
+ * spelling heuristic, though the spec reads an absent kind as `open`, and
+ * (2) laid the stages out by POSITION: everything from the first lost option
+ * on went into the separated group, so a lost option authored mid-list pulled
+ * the open and won options after it out of the forward path.
+ *
+ * Rows:
+ *   (a) a lost option authored mid-list sits apart, and the open and won
+ *       options authored after it stay on the forward path, won last;
+ *   (b) an option without a kind on a field that declares kinds reads as
+ *       open, whatever its spelling;
+ *   (c) every declared won option is a terminus, not only the last one;
+ *   (d) the spelling fallback (no kind on any option) warns once in a dev
+ *       build, naming the field and the guessed stages; nothing warns once a
+ *       kind is declared, nor when the fallback guessed nothing.
+ *
+ * Resolution: `../../index` is this package's own source, and
+ * `@object-ui/react` / `@object-ui/i18n` map to their `src` through the root
+ * `vitest.config.mts` alias table, so no `dist/` sits between this file and
+ * the renderer.
+ */
+
+import * as React from 'react';
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import '@testing-library/jest-dom';
+import { render, cleanup, within, type RenderResult } from '@testing-library/react';
+import type { SelectOptionKind } from '@objectstack/spec/data';
+import { I18nProvider } from '@object-ui/i18n';
+import { RecordContextProvider, SchemaRenderer } from '@object-ui/react';
+// Registers `record:path`, the block under test.
+import '../../index';
+
+type Option = { value: string; label: string; kind?: SelectOptionKind };
+
+const defOf = (name: string, options: Option[]) => ({
+  name,
+  label: name,
+  fields: { status: { name: 'status', label: 'Status', type: 'select', options } },
+});
+
+/** The spec's own lead order would be fine; this one authors the lost option mid-list. */
+const LEAD_LOST_MIDLIST = defOf('kind_lead', [
+  { value: 'new', label: 'New', kind: 'open' },
+  { value: 'unqualified', label: 'Unqualified', kind: 'lost' },
+  { value: 'qualified', label: 'Qualified', kind: 'open' },
+  { value: 'converted', label: 'Converted', kind: 'won' },
+]);
+
+/** Kinds declared on two options; `closed_lost` declares none. */
+const PARTIAL = defOf('kind_partial', [
+  { value: 'prospecting', label: 'Prospecting', kind: 'open' },
+  { value: 'closed_lost', label: 'Closed Lost' },
+  { value: 'activated', label: 'Activated', kind: 'won' },
+]);
+
+const TWO_WON = defOf('kind_two_won', [
+  { value: 'open_case', label: 'Open', kind: 'open' },
+  { value: 'resolved', label: 'Resolved', kind: 'won' },
+  { value: 'cancelled', label: 'Cancelled', kind: 'lost' },
+  { value: 'workaround', label: 'Workaround', kind: 'won' },
+]);
+
+const SPELLED_UNDECLARED = defOf('spelled_deal', [
+  { value: 'prospecting', label: 'Prospecting' },
+  { value: 'closed_won', label: 'Closed Won' },
+  { value: 'closed_lost', label: 'Closed Lost' },
+]);
+
+const PLAIN_UNDECLARED = defOf('plain_loan', [
+  { value: 'borrowed', label: 'Borrowed' },
+  { value: 'returned', label: 'Returned' },
+]);
+
+const NODE = { type: 'record:path', properties: { statusField: 'status' } };
+
+function mount(def: { name: string }, status: string): RenderResult {
+  return render(
+    <I18nProvider config={{ defaultLanguage: 'en', detectBrowserLanguage: false }}>
+      <RecordContextProvider
+        objectName={def.name}
+        recordId="r1"
+        data={{ id: 'r1', status }}
+        objectSchema={def as never}
+      >
+        <SchemaRenderer schema={NODE as never} />
+      </RecordContextProvider>
+    </I18nProvider>,
+  );
+}
+
+/** Both rows (desktop and mobile), in DOM order. */
+function rowsOf(r: RenderResult): [HTMLElement, HTMLElement] {
+  const text = r.container.textContent ?? '';
+  expect(text).not.toContain('failed to render');
+  expect(text).not.toContain('no stages configured');
+  const rows = Array.from(r.container.querySelectorAll('[role="list"]')) as HTMLElement[];
+  expect(rows).toHaveLength(2);
+  return [rows[0], rows[1]];
+}
+
+const stagesOf = (row: HTMLElement): HTMLElement[] => within(row).getAllByRole('listitem');
+const textOf = (stage: HTMLElement): string => (stage.textContent ?? '').replace(/[✓✗]/g, '').trim();
+const terminalsOf = (row: HTMLElement): Array<string | null> =>
+  stagesOf(row).map((s) => s.getAttribute('data-stage-terminal'));
+
+/** The desktop row's forward rail (the first stage's box) and separated group. */
+function desktopGroups(desktop: HTMLElement): { forward: string[]; separated: string[] } {
+  const stages = stagesOf(desktop);
+  const forwardBox = stages[0].parentElement;
+  return {
+    forward: stages.filter((s) => s.parentElement === forwardBox).map(textOf),
+    separated: stages.filter((s) => s.parentElement !== forwardBox).map(textOf),
+  };
+}
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+describe('(a) a declared kind lays the path out, not the option order (objectstack#26612)', () => {
+  it('a lost option authored mid-list sits apart; open steps, then the won terminus', () => {
+    const [desktop, mobile] = rowsOf(mount(LEAD_LOST_MIDLIST, 'qualified'));
+    expect(desktopGroups(desktop)).toEqual({
+      forward: ['New', 'Qualified', 'Converted'],
+      separated: ['Unqualified'],
+    });
+    expect(terminalsOf(desktop)).toEqual([null, null, 'won', 'lost']);
+    // The mobile row reads the same laid-out array, in the same order.
+    expect(stagesOf(mobile).map(textOf)).toEqual(['New', 'Qualified', 'Converted', 'Unqualified']);
+    expect(terminalsOf(mobile)).toEqual([null, null, 'won', 'lost']);
+    // Progress follows the laid-out order: New is travelled, Qualified current.
+    expect(stagesOf(desktop).map((s) => s.getAttribute('data-stage-state'))).toEqual([
+      'completed',
+      'current',
+      'upcoming',
+      'upcoming',
+    ]);
+  });
+
+  it('a record in the lost state marks the lost stage current, apart from the rail', () => {
+    const [desktop, mobile] = rowsOf(mount(LEAD_LOST_MIDLIST, 'unqualified'));
+    const lost = stagesOf(desktop)[3];
+    expect(textOf(lost)).toBe('Unqualified');
+    expect(lost).toHaveAttribute('data-stage-state', 'current');
+    expect(lost).toHaveAttribute('data-stage-terminal', 'lost');
+    expect(stagesOf(mobile)[3]).toHaveAttribute('data-stage-state', 'current');
+  });
+});
+
+describe('(b) once the field declares a kind, nothing is guessed from spelling (objectstack#26612)', () => {
+  it('an option without a kind reads as open, though it is spelled closed_lost', () => {
+    const [desktop, mobile] = rowsOf(mount(PARTIAL, 'prospecting'));
+    expect(desktopGroups(desktop)).toEqual({
+      forward: ['Prospecting', 'Closed Lost', 'Activated'],
+      separated: [],
+    });
+    expect(terminalsOf(desktop)).toEqual([null, null, 'won']);
+    expect(terminalsOf(mobile)).toEqual([null, null, 'won']);
+  });
+});
+
+describe('(c) every declared won option is a terminus (objectstack#26612)', () => {
+  it('two won options both end the forward path, in their authored order', () => {
+    const [desktop, mobile] = rowsOf(mount(TWO_WON, 'open_case'));
+    expect(desktopGroups(desktop)).toEqual({
+      forward: ['Open', 'Resolved', 'Workaround'],
+      separated: ['Cancelled'],
+    });
+    expect(terminalsOf(desktop)).toEqual([null, 'won', 'won', 'lost']);
+    expect(terminalsOf(mobile)).toEqual([null, 'won', 'won', 'lost']);
+  });
+});
+
+describe('(d) the spelling fallback warns in a dev build, naming the field (objectstack#26612)', () => {
+  const pathWarnings = (spy: { mock: { calls: unknown[][] } }): string[] =>
+    spy.mock.calls.map((c: unknown[]) => String(c[0])).filter((m: string) => m.startsWith('record:path'));
+
+  it('no kind on any option: the guess still lays the path out, and warns once', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const r = mount(SPELLED_UNDECLARED, 'prospecting');
+    const [desktop] = rowsOf(r);
+    // The fallback renders as before.
+    expect(desktopGroups(desktop)).toEqual({ forward: ['Prospecting', 'Closed Won'], separated: ['Closed Lost'] });
+    expect(terminalsOf(desktop)).toEqual([null, 'won', 'lost']);
+
+    const messages = pathWarnings(warn);
+    expect(messages).toHaveLength(1);
+    expect(messages[0]).toContain('field "status"');
+    expect(messages[0]).toContain('object "spelled_deal"');
+    expect(messages[0]).toContain('"closed_won", "closed_lost"');
+
+    // Re-rendering the same picklist does not repeat it.
+    cleanup();
+    rowsOf(mount(SPELLED_UNDECLARED, 'closed_won'));
+    expect(pathWarnings(warn)).toHaveLength(1);
+  });
+
+  it('a field that declares kinds never warns', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    rowsOf(mount(PARTIAL, 'prospecting'));
+    rowsOf(mount(LEAD_LOST_MIDLIST, 'new'));
+    expect(pathWarnings(warn)).toEqual([]);
+  });
+
+  it('no kind declared and nothing guessed: no warning', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const [desktop] = rowsOf(mount(PLAIN_UNDECLARED, 'borrowed'));
+    expect(terminalsOf(desktop)).toEqual([null, null]);
+    expect(pathWarnings(warn)).toEqual([]);
+  });
+});
@@ -69,6 +69,24 @@ const splitDesigner = (props: Record<string, any>) => {
   return { designer: { 'data-obj-id': id, 'data-obj-type': type, style }, rest };
 };
 
+/**
+ * Dev mode, in this repository's established spelling for it — the build's
+ * `NODE_ENV`, read per call — the guard `record-related-list.tsx`,
+ * `plugin-gantt` and `plugin-map` put on their authoring diagnostics. The
+ * spelling-guess warning below is feedback for whoever wrote the picklist; a
+ * production bundle does not pay for it.
+ */
+const isDevBuild = (): boolean =>
+  (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env
+    ?.NODE_ENV !== 'production';
+
+/**
+ * The (object, field, guessed stages) triples already warned about, so a path
+ * re-rendering with the same picklist warns once, while a new guess on the
+ * same field (an option added) is reported afresh.
+ */
+const warnedSpellingGuesses = new Set<string>();
+
 /**
  * The label of a terminal stage on the desktop row: centred, and WRAPPING
  * rather than truncated or held on one line, so the stage that ends the path
@@ -243,28 +261,74 @@ export const RecordPathRenderer: React.FC<RecordPathRendererProps> = ({
   //      — `open` included, which is how a declared open stage spelled like a
   //      terminal stays a middle step: the spec's strict `stages[]` row can
   //      carry `won` / `lost`, so step 1 cannot say "open";
-  //   3. only for options that declare no kind, a spelling heuristic, so CRM
-  //      examples / Salesforce-style picklists ("closed_won", "closed_lost",
-  //      "失败", "流失") get the right treatment without a migration.
+  //   3. only when the status field declares NO kind on any of its options, a
+  //      spelling heuristic, so CRM examples / Salesforce-style picklists
+  //      ("closed_won", "closed_lost", "失败", "流失") get the right treatment
+  //      without a migration — with a dev-build warning naming the field, so
+  //      the author learns the layout is a guess (objectstack#26612).
+  //
+  // Once the field declares a kind, an option that declares none reads as
+  // `open` — the spec's own rule for an absent kind ("Absent reads as 'open'",
+  // `SelectOption.kind`) — and is never guessed from its spelling: a declared
+  // vocabulary with a guess filling its gaps would be two contracts at once.
   const LOST_TOKENS = /(^|[_-\s])(closed_)?(lost|failed?|cancell?ed|失败|流失|丢单|败)([_-\s]|$)/i;
   const WON_TOKENS = /(^|[_-\s])(closed_)?(won|success|成交|赢|完成)([_-\s]|$)/i;
-  const classify = (s: { value: any; label?: string; terminal?: 'won' | 'lost' }): 'won' | 'lost' | undefined => {
-    if (s.terminal) return s.terminal;
-    const declared = declaredKinds?.get(s.value);
-    if (declared !== undefined) return stageTerminalOfKind(declared);
+  const guessTerminal = (s: { value: any; label?: string }): 'won' | 'lost' | undefined => {
     const probe = `${String(s.value ?? '')} ${String(s.label ?? '')}`;
     if (LOST_TOKENS.test(probe)) return 'lost';
     if (WON_TOKENS.test(probe)) return 'won';
     return undefined;
   };
-  const stageKinds = stages.map(classify);
+  const classify = (s: { value: any; label?: string; terminal?: 'won' | 'lost' }): 'won' | 'lost' | undefined => {
+    if (s.terminal) return s.terminal;
+    if (declaredKinds) return stageTerminalOfKind(declaredKinds.get(s.value));
+    return guessTerminal(s);
+  };
+
+  // The stages the spelling heuristic classified — what the dev-build warning
+  // below names. Always empty once the field declares a kind.
+  const guessedStages: string[] = declaredKinds
+    ? []
+    : stages.filter((s) => !s.terminal && guessTerminal(s) !== undefined).map((s) => String(s.value));
+  const guessWarningKey = guessedStages.length > 0
+    ? JSON.stringify([ctx?.objectName ?? null, statusField ?? null, guessedStages])
+    : null;
+  React.useEffect(() => {
+    if (guessWarningKey === null || !isDevBuild() || warnedSpellingGuesses.has(guessWarningKey)) return;
+    warnedSpellingGuesses.add(guessWarningKey);
+    const [objectName, field, guessed] = JSON.parse(guessWarningKey) as [string | null, string | null, string[]];
+    const subject = field
+      ? `field "${field}"${objectName ? ` of object "${objectName}"` : ''} declares no option \`kind\``
+      : 'the authored stages name no field that declares an option `kind`';
+    console.warn(
+      `record:path — ${subject}, so stage(s) ${guessed.map((v) => `"${v}"`).join(', ')} ` +
+        `were classified won/lost from their spelling. Declare \`kind: 'open' | 'won' | 'lost'\` ` +
+        'on every option of the field to lay the path out by lifecycle instead of by name.',
+    );
+  }, [guessWarningKey]);
+
+  // WHERE each stage sits. A field that declares kinds is laid out BY kind:
+  // its open options as the steps, in their authored order, then its won
+  // option(s) as the forward terminus, then its lost option(s) in the
+  // separated group — so a lost option authored mid-list never reads as step
+  // N, and a won option authored after a lost one never lands in the lost
+  // group (objectstack#26612). The sort is stable, so each class keeps its
+  // authored order. Without declared kinds the layout stays POSITIONAL, as
+  // the spelling fallback has always drawn it.
+  const KIND_RANK = { open: 0, won: 1, lost: 2 } as const;
+  const classified = stages.map((stage) => ({ stage, kind: classify(stage) }));
+  const placed = declaredKinds
+    ? [...classified].sort((a, b) => KIND_RANK[a.kind ?? 'open'] - KIND_RANK[b.kind ?? 'open'])
+    : classified;
+  const pathStages: PathStage[] = placed.map((p) => p.stage);
+  const stageKinds = placed.map((p) => p.kind);
   // Find the index of the FIRST lost-class stage so we can render it
   // (and any subsequent lost terminals) as a visually separated alt
   // group. Won-class stages stay inside the forward path — they're the
   // successful terminus.
   const firstLostIdx = stageKinds.findIndex((k) => k === 'lost');
-  const forwardStages = firstLostIdx === -1 ? stages : stages.slice(0, firstLostIdx);
-  const lostStages = firstLostIdx === -1 ? [] : stages.slice(firstLostIdx);
+  const forwardStages = firstLostIdx === -1 ? pathStages : pathStages.slice(0, firstLostIdx);
+  const lostStages = firstLostIdx === -1 ? [] : pathStages.slice(firstLostIdx);
   // ── ONE classification, computed once, read by BOTH rows (objectui#5998) ──
   //
   // The desktop and the mobile row below render the same `stages[]`, and each
@@ -293,16 +357,21 @@ export const RecordPathRenderer: React.FC<RecordPathRendererProps> = ({
   // Conservative on both axes: this can only ever STOP marking a stage as a
   // terminus, never start. No stage gains a `terminal` on either row that it
   // did not already carry on that row.
+  //
+  // The `idx === last` restriction guards the SPELLING guess (`完成` mid-path).
+  // A declared `won` is no guess, and the by-kind layout above has already put
+  // every won option at the forward tail, so each one is a terminus
+  // (objectstack#26612).
   const lastForwardIdx = forwardStages.length - 1;
   const stageTerminals: Array<'won' | 'lost' | undefined> = stageKinds.map((kind, idx) =>
-    kind === 'won' ? (idx === lastForwardIdx ? 'won' : undefined) : kind,
+    kind === 'won' ? (declaredKinds || idx === lastForwardIdx ? 'won' : undefined) : kind,
   );
 
-  let currentIdx = stages.findIndex((s) => s.value === current);
+  let currentIdx = pathStages.findIndex((s) => s.value === current);
   if (currentIdx < 0) currentIdx = -1;
   const currentInLost = firstLostIdx !== -1 && currentIdx >= firstLostIdx;
 
-  if (stages.length === 0) {
+  if (pathStages.length === 0) {
     // Names the field when the derivation had an object definition to read
     // and found no picklist options on `statusField` (objectui#11106): the
     // author learns which field to fix, or that `stages` must be authored.
@@ -508,7 +577,7 @@ export const RecordPathRenderer: React.FC<RecordPathRendererProps> = ({
         className="flex sm:hidden w-full items-start gap-2 overflow-x-auto pb-1 -mx-1 px-1 [-ms-overflow-style:none] [scrollbar-width:none] [&::-webkit-scrollbar]:hidden"
         {...railAria}
       >
-        {stages.map((stage, idx) => {
+        {pathStages.map((stage, idx) => {
           const terminal = stageTerminals[idx];
           const isLost = terminal === 'lost';
           const isCompleted = !isLost && !currentInLost && currentIdx >= 0 && idx < currentIdx;