Defer sort seed checks until adjust-order startup

.trellis/spec/frontend/state-management.md

@@ -0,0 +1,87 @@
+# State Management
+
+> How state is managed in this project.
+
+---
+
+## Overview
+
+This WPF application uses view models as both UI state containers and command
+workflow coordinators. Some view model methods are reused by interactive UI
+paths and startup/headless capability checks, so state that triggers UI prompts
+or file writes must be explicitly controlled by the caller.
+
+---
+
+## State Categories
+
+### View Model Workflow Flags
+
+Use explicit boolean workflow flags when the same view model method can run in
+different interaction contexts.
+
+Example:
+
+```csharp
+var viewModel = new MainWindowViewModel
+{
+    ShouldCheckSortFileOnLoad = false
+};
+```
+
+`MainWindowViewModel.LoadToolsFromDrillTape` can parse a drill tape for the main
+window, startup menu capability checks, and headless startup actions. Only the
+main window adjustment workflow should allow load-time sort seed prompts.
+
+---
+
+## When to Use Global State
+
+<!-- Criteria for promoting state to global -->
+
+(To be filled by the team)
+
+---
+
+## Server State
+
+<!-- How server data is cached and synchronized -->
+
+(To be filled by the team)
+
+---
+
+## Common Mistakes
+
+### Triggering Interactive Side Effects During Capability Checks
+
+Capability checks such as startup menu button visibility should not trigger
+interactive prompts, file saves, Explorer windows, or reorder operations.
+
+Wrong:
+
+```csharp
+var viewModel = new MainWindowViewModel
+{
+    IsStartupDrillTapeFile = true,
+    OriginalFilePath = filePath
+};
+
+viewModel.LoadToolsFromDrillTape(content);
+```
+
+Correct:
+
+```csharp
+var viewModel = new MainWindowViewModel
+{
+    IsStartupDrillTapeFile = true,
+    OriginalFilePath = filePath,
+    ShouldCheckSortFileOnLoad = false
+};
+
+viewModel.LoadToolsFromDrillTape(content);
+```
+
+Before reusing a view model method in a startup, preview, export, or background
+path, check whether it reads state that can show dialogs or mutate files.