@@ -337,7 +337,38 @@ Build conventions the result must satisfy (confirm each in the diff):
    mode for them.
 4. Legacy-mode smoke: with the toggle OFF, every launch site from the
    analysis document still opens the legacy dialog unchanged.
-5. Add any new exemplars created during this conversion to the exemplar map
+5. Work each manual finding through
+   [The manual-finding loop](#the-manual-finding-loop).
+6. Add any new exemplars created during this conversion to the exemplar map
    (the promotion row from Planning the replacement, if not already landed).
-6. Land: comment audit against the repository standard, preflight the
+7. Land: comment audit against the repository standard, preflight the
    branch, and PR per the repo's conventions.
+
+### The manual-finding loop
+
+A green suite that missed a defect the developer found by looking is evidence
+the SUITE has a hole, not just the code. Close both.
+
+1. **Triage the layer before writing anything.** ViewModel, launcher edge, or
+   rendered view? Existing green tests narrow it in one step: if the ViewModel
+   tests pass and the dialog looks wrong, the state is right and the defect is
+   below it.
+2. **Write the missing test at the layer the defect lives in**, before the
+   fix. A ViewModel-only suite cannot see a control that draws nothing; a
+   render-layer defect needs a render-layer test.
+3. **Verify the new test actually catches the defect: revert the fix (or
+   write the test first) and watch it FAIL.** This is not ceremony. A test
+   asserting a control "renders" can pass against a control drawing nothing --
+   an untemplated Avalonia control still measures to its padding and still has
+   visual children. A test that has never failed proves nothing, and a
+   false-green test is worse than no test because it silences the next person.
+4. **Fix, then re-run the owning suite AND every suite the change reaches.**
+   A shared control, style, or seam means the blast radius is not the dialog.
+5. **Record it in the working documents**: the cause, the fix, and -- when the
+   first test attempt was a false green -- which assertion was too weak and
+   which one actually bites. That lesson is the reusable part.
+
+If the finding turns out to be a scope decision rather than a defect (a
+control nobody planned, a behavior the plan never covered), do not absorb it
+silently: put it to the developer as a decision, and if they take it in, add
+plan items for it rather than implementing untested.
@@ -44,6 +44,25 @@ convert-dialog: `Docs/migration/working/<SliceClass>/` holding
 `<SliceClass>-design.md`; detect-and-resume on re-invocation; the documents
 remain after completion (retention is the developer's call).
 
+**Every working document opens with a LINKED ticket reference whenever a ticket
+is involved.** Write the Jira key as a markdown link to
+`https://jira.sil.org/browse/<KEY>`, never as bare text, and link the parent or
+epic the same way when there is one:
+
+```markdown
+Ticket: [LT-22672](https://jira.sil.org/browse/LT-22672) "[Avalonia] Convert
+Allomorphs slice", parent [LT-22622](https://jira.sil.org/browse/LT-22622).
+```
+
+These documents are gitignored and outlive the session that wrote them, so a
+reader arriving later has no other route back to the ticket. It applies to the
+analysis, test plan, design report, and state manifest alike.
+
+This does NOT license ticket keys as pointers in code comments. Comment hygiene
+governs there: a bare finding-code such as `P1:` referring to one of these
+documents is a banned doc-pointer, because the document it points into is not
+in the repository.
+
 ### Citing other documents and sections
 
 Every reference -- to another document OR to a section of the document you
@@ -184,8 +203,46 @@ is worse than an honest Unsupported row for preview users).
 1. create-integration-test against the plan (tests land per the mirroring
    rule: control tests in `FwAvaloniaTests/Detail/`, composer tests in
    `xWorksTests/Avalonia/Composer/`).
-2. Developer manual test in live FieldWorks, New UI on: the field at its
-   real position, edit interactions per the analysis document, focus-loss
-   autosave, single Ctrl+Z per save, cross-framework PropChanged refresh both
-   directions, tool-switch mid-edit settles cleanly.
-3. Land the exemplar-promotion row for anything new (human-gated, same PR).
+2. Ask the developer to manually test -- then STOP and wait for their
+   findings. They own the app; do not drive it or change its UI mode for
+   them. In live FieldWorks, New UI on: the field at its real position, edit
+   interactions per the analysis document, focus-loss autosave, single Ctrl+Z
+   per save, cross-framework PropChanged refresh both directions, tool-switch
+   mid-edit settles cleanly.
+3. Legacy-mode smoke: with the UI-mode toggle OFF, every field the change
+   touched still behaves unchanged. A composer or shared-control change
+   reaches far beyond the slice being converted, so name what else it reaches
+   and have that checked too.
+4. Work each manual finding through
+   [The manual-finding loop](#the-manual-finding-loop).
+5. Land the exemplar-promotion row for anything new (human-gated, same PR).
+
+### The manual-finding loop
+
+A green suite that missed a defect the developer found by looking is evidence
+the SUITE has a hole, not just the code. Close both.
+
+1. **Triage the layer before writing anything.** Model (composer), dispatch
+   (factory), or render (control)? Existing green tests narrow it in one step:
+   if the composer tests pass and the row looks wrong, the model is right and
+   the defect is below it.
+2. **Write the missing test at the layer the defect lives in**, before the
+   fix. A model-only plan cannot see a control that draws nothing; a
+   render-layer defect needs a render-layer test.
+3. **Verify the new test actually catches the defect: revert the fix (or
+   write the test first) and watch it FAIL.** This is not ceremony. A test
+   asserting a control "renders" can pass against a control drawing nothing --
+   an untemplated Avalonia control still measures to its padding and still has
+   visual children. A test that has never failed proves nothing, and a
+   false-green test is worse than no test because it silences the next person.
+4. **Fix, then re-run the owning suite AND every suite the change reaches.**
+   Shared code (the composer, `SliceFactory`, a shared control style) means
+   the blast radius is not the slice.
+5. **Record it in `<SliceClass>-state.md`**: the cause, the fix, and -- when
+   the first test attempt was a false green -- which assertion was too weak
+   and which one actually bites. That lesson is the reusable part.
+
+If the finding turns out to be a scope decision rather than a defect (a row
+nobody planned, a behavior the plan never covered), do not absorb it silently:
+put it to the developer as a decision, and if they take it in, add plan items
+for it rather than implementing untested.
@@ -68,6 +68,8 @@ migration burden.
 | Localization | `FwAvaloniaDialogsStrings` accessor + neutral resx (dialog-conversion.md §5) |
 | Clipboard in text fields | `IFwClipboard` seam (`Src/Common/FwAvalonia/Seams/`) |
 | Headless ViewModel/view tests | `FwAvaloniaDialogsTests/EntryGoDialogTests.cs` shapes; launcher-over-real-cache: `LcmLinkMsaDialogLauncherTests.cs` |
+| List-editor jump from a chooser row ("Edit the … list") | `DetailGearChrome.CreateConfigureGear` (row gear → `DetailLinkRequest` → `FollowLink`); links built by `DetailComposer.CreateChooserLinks`. **Approved divergence:** the detail view synthesizes the link for ANY possibility-list row the layout left linkless and puts it on the row, where legacy synthesizes only for `autoCustom` and puts it inside the chooser dialog. Reason and approver are in the `CreateChooserLinks` doc — do not "fix" it back to the legacy trigger. |
+| Adding to a reference-vector field | `FwReferenceVectorField`'s "+" opens `FwOptionChooser` in multi-select; the per-item right-click removes. **Approved divergence:** current members ride as UNAVAILABLE keys, so they list greyed and un-toggleable rather than pre-checked; legacy's `SimpleListChooser` pre-checks them and treats the dialog as setting the whole membership. "+" means add, and the row owns removal. Reason and approver are in the `FwReferenceVectorField` class doc. |
 
 ## 3. Gap register — the first implementation becomes the exemplar
 
 
@@ -72,6 +72,7 @@ It is intentionally not a full architecture manual. It should stay biased toward
 - **Cross-namespace twin**: A deliberate reuse of a legacy type name for its Avalonia counterpart (`FwAvalonia.Detail.DataTree` beside `DetailControls.DataTree`; `SliceFactory`, `MSAGroupBox`). Disambiguate with a `using` alias at the call site; never rename the type to dodge the collision. The twins cover only the half of the legacy responsibility that still fits — the Avalonia `DataTree` renders a prebuilt `DetailModel` and does not compose it.
 - **Slice plugin**: A custom Avalonia row editor (`ISlicePlugin`) registered in `SlicePluginRegistry` under the exact legacy layout `class=` string, so migrating a slice edits no layout XML. Registration throws on a double claim: one owner per legacy class.
 - **Unsupported row**: The labeled row `SliceFactory` builds when no field kind, plugin, or control matches. Unmigrated work is always visible and never silently omitted; the set of these rows is the remaining conversion worklist.
+- **Hotlinks**: The always-visible strip of section-level commands under a DataTree section header — the layout `hotlinks=` attribute, `DetailField.HotlinksId`, the `-Hotlinks` menu-id suffix, legacy `SummaryCommandControl`, Avalonia `DataTree.CreateHotlinkStrip`. Say **hotlinks**, not "quick links": the latter appears nowhere in the repo. Legacy paints one clickable label per command with per-command enabled state.
 - **Seam**: A framework-neutral substitution point that lets the Avalonia layer consume product behavior without referencing LCModel or WinForms — `IEditSession`, `IUiScheduler`, `IDetailLifetime`, `IDetailRefreshCoordinator`, `IXCoreCommandBridge`, `IRecordNavigationContext` in `FwAvalonia/Seams`, alongside boundary data contracts such as `IFwClipboard`. Product implementations live at the xWorks edge. Deliberately narrow: direct Avalonia APIs remain allowed at the UI edge, and `Seams/` holds only real substitution points — not helpers that merely live near one.
 - **Fenced edit session**: One `IEditSession` wrapping one LCModel undo task, opened lazily on the first staged edit and ended exactly once by Commit or Cancel. Prevents orphaned undo tasks; implemented by `LcmDetailEditSession`.
 - **Settle**: The single auto-save policy for an open edit session — commit if valid, otherwise roll back and notify. Invoked on navigation, window deactivate, undo, and teardown (`DetailEditContextHolder.Settle`).
@@ -88,6 +89,7 @@ It is intentionally not a full architecture manual. It should stay biased toward
 - User-visible UI strings belong in `.resx`, not hardcoded source.
 - Installer work lives under `FLExInstaller/`.
 - Integration tests often depend on deterministic sample data such as `TestLangProj/`.
+- DataTree object commands split by test environment. Insert commands are always enabled, so they run headlessly end-to-end through `MockFwXWindow` -> `XCoreMenuBridge` -> mediator -> unit of work (see `DetailObjectCommandExecutionTests`). Delete, Move, Demote, and Merge only materialize and enable when xCore display handlers can read live slice-sequence context from a laid-out, VISIBLE legacy DataTree, which headless runs do not have; those tests are `[Explicit]` and desktop-environment only. Do not write a plan or a claim that implies headless coverage of the second group.
 - Worktree-aware scripts are preferred because concurrent work across git worktrees is supported.
 - Visual Studio and MSVC toolset versions are policy-driven from `Build/FieldWorks.Toolchain.props`; never hardcode them in projects, scripts, or docs.
 - FLEx/Language Explorer is built with architectural boundaries, new dependencies between existing projects must be justified.
 
@@ -27,6 +27,15 @@ public abstract class AvaloniaHostControlBase : System.Windows.Forms.UserControl
 		/// <summary>Raised after a hosted detail view reports an edit completed (wired by the derived host).</summary>
 		public event EventHandler DetailEditCompleted;
 
+		/// <summary>Raised when the hosted detail view goes idle: the click finished and no
+		/// picker it opened is still up.</summary>
+		public event EventHandler DetailInteractionCompleted;
+
+		/// <summary>Whether a click is in flight in the hosted detail view, or a picker it opened
+		/// is still up. Rebuilding while this is true destroys what the user is interacting
+		/// with.</summary>
+		public virtual bool IsDetailInteractionInFlight => false;
+
 		protected AvaloniaHostControlBase()
 		{
 			FwAvaloniaRuntime.EnsureInitialized();
@@ -64,6 +73,9 @@ protected AvaloniaHostControlBase()
 
 		protected void RaiseDetailEditCompleted() => DetailEditCompleted?.Invoke(this, EventArgs.Empty);
 
+		protected void RaiseDetailInteractionCompleted()
+			=> DetailInteractionCompleted?.Invoke(this, EventArgs.Empty);
+
 		/// <summary>Swaps the hosted Avalonia content and shows the control.</summary>
 		protected void SetHostContent(Avalonia.Controls.Control content)
 		{
 
@@ -32,7 +32,7 @@ namespace SIL.FieldWorks.Common.FwAvalonia.Detail
 	/// undo step per field, no Save/Cancel buttons. Validation failures show inline and block the
 	/// commit; Escape rolls the session back. Without a context the view is read-only display.
 	/// </summary>
-	public sealed class DataTree : UserControl
+	public sealed class DataTree : UserControl, IDetailPopupSink
 	{
 		private readonly IDetailEditContext _editContext;
 		private readonly Action<string> _writingSystemFocused;
@@ -217,8 +217,41 @@ public DataTree(DetailModel model, IDetailEditContext editContext = null,
 				if (_editContext != null && _editContext.IsOpen)
 					OnSave();
 			}, Avalonia.Interactivity.RoutingStrategies.Bubble);
+
+			// A click on another row autosaves and re-shows, rebuilding controls between press
+			// and release. Tunnel, to beat any descendant to the press.
+			AddHandler(Avalonia.Input.InputElement.PointerPressedEvent, (s, e) =>
+				_pointerGestureActive = true,
+				Avalonia.Interactivity.RoutingStrategies.Tunnel, handledEventsToo: true);
+			// Bubble, so descendants finish the gesture (a checkbox toggles, and may itself
+			// commit) before the held re-show is released.
+			AddHandler(Avalonia.Input.InputElement.PointerReleasedEvent, (s, e) => EndPointerGesture(),
+				Avalonia.Interactivity.RoutingStrategies.Bubble, handledEventsToo: true);
+		}
+
+		// A press that takes no capture, released after the pointer leaves the view, bubbles
+		// nowhere near this control. The top level catches it, so no gesture outlives its
+		// button and wedges the view busy.
+		protected override void OnAttachedToVisualTree(VisualTreeAttachmentEventArgs e)
+		{
+			base.OnAttachedToVisualTree(e);
+			_topLevel = e.Root as Avalonia.Input.InputElement;
+			_topLevel?.AddHandler(Avalonia.Input.InputElement.PointerReleasedEvent,
+				OnTopLevelPointerReleased, Avalonia.Interactivity.RoutingStrategies.Bubble,
+				handledEventsToo: true);
+		}
+
+		protected override void OnDetachedFromVisualTree(VisualTreeAttachmentEventArgs e)
+		{
+			_topLevel?.RemoveHandler(Avalonia.Input.InputElement.PointerReleasedEvent,
+				(EventHandler<Avalonia.Input.PointerReleasedEventArgs>)OnTopLevelPointerReleased);
+			_topLevel = null;
+			base.OnDetachedFromVisualTree(e);
 		}
 
+		private void OnTopLevelPointerReleased(object sender,
+			Avalonia.Input.PointerReleasedEventArgs e) => EndPointerGesture();
+
 		/// <summary>
 		/// Re-derives everything that depends on the label column's width, from that width. The
 		/// grid column is the source and this is its only consumer, so the three derived values
@@ -270,9 +303,21 @@ private void OnViewKeyDown(object sender, Avalonia.Input.KeyEventArgs e)
 		/// </summary>
 		public event EventHandler EditCompleted;
 
+		/// <summary>
+		/// Whether a pointer press is in flight anywhere in this view. A host must not rebuild
+		/// these controls while it is true: the release would reach a detached control and the
+		/// click would do nothing.
+		/// </summary>
+		public bool IsInteractionInFlight => _pointerGestureActive || _openPickers > 0;
+
+		/// <summary>
+		/// Raised when the view goes idle again -- the click finished and no picker it
+		/// opened is still up -- so a host holding a refresh can deliver it.
+		/// </summary>
+		public event EventHandler InteractionCompleted;
+
 		// 14.4: no Save/Cancel buttons -- the legacy view saves as you go. The footer carries
-		// only the
-		// inline validation messages (a failed autosave is never silent).
+		// only the inline validation messages (a failed autosave is never silent).
 		private Control CreateEditFooter()
 		{
 			_validationBlock = new TextBlock
@@ -303,16 +348,84 @@ private void OnSave()
 
 			_validationBlock.IsVisible = false;
 			_editContext.Commit();
-			EditCompleted?.Invoke(this, EventArgs.Empty);
+			RaiseOrDeferEditCompleted();
 		}
 
 		private void OnCancel()
 		{
 			_validationBlock.IsVisible = false;
 			_editContext.Cancel();
+			RaiseOrDeferEditCompleted();
+		}
+
+		// True between a pointer press and its release anywhere in this view.
+		private bool _pointerGestureActive;
+		// The window this view is in, while it is in one: the backstop for a release the view
+		// itself never sees.
+		private Avalonia.Input.InputElement _topLevel;
+		// Pickers opened FROM this view. Their flyouts anchor to a control inside it, so a
+		// rebuild destroys the anchor and the picker vanishes mid-choice.
+		private int _openPickers;
+		private bool _editCompletedHeld;
+
+		/// <summary>
+		/// Raises the completion the host re-shows on -- unless a pointer gesture is in flight,
+		/// in which case it waits for the release. The commit itself is NOT delayed; only the
+		/// re-show is, because rebuilding mid-click destroys the control the press landed on.
+		/// </summary>
+		private void RaiseOrDeferEditCompleted()
+		{
+			if (IsInteractionInFlight)
+			{
+				_editCompletedHeld = true;
+				return;
+			}
+
 			EditCompleted?.Invoke(this, EventArgs.Empty);
 		}
 
+		// One re-show per gesture however many commits it produced: the focus-loss autosave of
+		// the field being left, and any commit by the control being clicked, coalesce into this.
+		private void EndPointerGesture()
+		{
+			if (!_pointerGestureActive)
+				return;
+			_pointerGestureActive = false;
+			DeliverWhenIdle();
+		}
+
+		/// <summary>
+		/// A click that opens a popup is not finished when the button is released -- the user is
+		/// still choosing. Rebuilding then would close it under them.
+		/// </summary>
+		public void PopupOpenChanged(bool open)
+		{
+			if (open)
+			{
+				_openPickers++;
+				return;
+			}
+
+			if (_openPickers > 0)
+				_openPickers--;
+			DeliverWhenIdle();
+		}
+
+		private void DeliverWhenIdle()
+		{
+			if (IsInteractionInFlight)
+				return;
+			if (_editCompletedHeld)
+			{
+				_editCompletedHeld = false;
+				EditCompleted?.Invoke(this, EventArgs.Empty);
+			}
+
+			// Always, even with no edit of our own: the commit's PropChanged may have left the
+			// host holding a refresh that only this signal releases.
+			InteractionCompleted?.Invoke(this, EventArgs.Empty);
+		}
+
 		// Viewing parity (11.x): a header owns every more-indented row up to the next row at its
 		// own indent or shallower; a row stays visible only while every owning header is
 		// expanded.
@@ -670,7 +783,9 @@ private Control CreateEditor(DetailField field, string automationId)
 				linkRequested: _linkRequested,
 				clipboard: _clipboard,
 				save: _editContext == null ? (Action)null : OnSave,
-				showWritingSystemAbbreviation: true,
+				// Legacy labels each alternative of a MultiStringSlice and leaves a StringSlice's
+				// single value unlabelled, so the gutter follows the row's own kind.
+				showWritingSystemAbbreviation: field.IsMultiStringRow,
 				wsAbbrevColumnWidth: _wsAbbrevColumnWidth));
 	}
 }