Plan Lexical Edit Avalonia migration and add coverage

.claude/skills/fieldworks-avalonia-ui/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: fieldworks-avalonia-ui
+description: "Build, review, or fix Avalonia UI code in FieldWorks: XAML, MVVM, view models, owned controls, headless tests, preview host, accessibility identity, and product-vs-preview wiring. Use for any change under Src/Common/FwAvalonia/, Src/Common/FwAvaloniaPreviewHost/, or Src/**/*.Avalonia/, and for net48/net8 Avalonia test changes — even if the request only mentions a control, a binding, a style, or a flaky UI test. For whole-surface migration planning use fieldworks-winforms-to-avalonia-migration first."
+---
+
+# FieldWorks Avalonia UI
+
+## Use This For
+
+- Avalonia XAML, view models, commands, lifetimes, dispatching, and
+  resource/style changes.
+- New or changed projects under `Src/**/**/*.Avalonia/`,
+  `Src/Common/FwAvalonia/`, and `Src/Common/FwAvaloniaPreviewHost/`.
+- Preview Host module registration, sample data providers, and UI
+  diagnostics (see `.github/instructions/avalonia.instructions.md` for
+  build/preview commands and project layout rules).
+- UI host wiring that selects between Avalonia and legacy UI — apply
+  `fieldworks-ui-wiring-review` alongside this skill.
+
+## Start From the Established Patterns
+
+Do not design controls or seams from scratch. The migration hub skill
+(`fieldworks-winforms-to-avalonia-migration`) documents the decided
+architecture; its `references/architecture-patterns.md` covers owned
+controls, writing-system text fields, dialogs/flyouts, validation, and
+lifetime. Canonical code to imitate:
+
+- Owned field controls: `Src/Common/FwAvalonia/Region/FwFieldControls.cs`,
+  `FwOptionPicker.cs`, `RegionMenuFlyout.cs`, `HoverReveal.cs`
+- Region view + focus memory: `LexicalEditRegionView.cs`,
+  `RegionFocusMemory.cs`
+- Seams (scheduler, lifetime, clipboard, edit sessions):
+  `Src/Common/FwAvalonia/Seams/ISeams.cs`
+- Headless test setup: `Src/Common/FwAvalonia/FwAvaloniaTests/TestAppBuilder.cs`;
+  examples in `RegionEditingTests.cs`, `VisualParityAndDensityTests.cs`
+- Density constants: `Src/Common/FwAvalonia/Poc/PocDensity.cs`
+
+## Required Checks
+
+- Use current Avalonia docs for uncertain APIs; do not guess dispatcher,
+  headless, automation, or binding behavior.
+- Keep product UI strings localizable (`FwAvaloniaStrings.resx` or the
+  StringTable lane); prototype hardcoded strings must be called out as gaps.
+- Stamp stable, nonlocalized `AutomationProperties.AutomationId` (derived
+  from IR `StableId` where applicable) and localized
+  `AutomationProperties.Name` on user-facing controls.
+- UI logic stays in bindings/view models where practical; avoid
+  logic-heavy code-behind.
+- For any Avalonia "select from a list" surface, prefer the shared
+  `FwOptionPicker` pattern in `Src/Common/FwAvalonia/Region/FwOptionPicker.cs`
+  (AutoCompleteBox-based, keyboard-safe, search-capable, compact density)
+  over ad hoc `ListBox` popups or one-off editable selectors. Reach for a raw
+  `ComboBox` only when the UX explicitly needs an always-visible inline combo
+  rather than the shared flyout selector.
+- Do not fix Avalonia keyboard, focus, filtering, selection, popup, or
+  rendering bugs by patching `System.Windows.Forms` hosts, WinForms
+  interop message handling, or other legacy host-only routes unless the
+  task explicitly targets interop behavior. Default to fixing the issue
+  inside the Avalonia control tree or Avalonia-owned seams.
+- Marshal to the UI thread through `IUiScheduler` (or Avalonia dispatcher
+  in non-region code); no hidden `Task.Run`, no sync-over-async.
+- Keep preview data lightweight unless the change explicitly opts into
+  LCModel/project data; product-facing paths use real edit-session/domain
+  contracts — detached DTO-only models remain preview-only.
+- Headless tests: simulate input on `Window`, flush with
+  `Dispatcher.UIThread.RunJobs()`, and capture visual regression frames
+  with Skia (`UseHeadlessDrawing=false` + `CaptureRenderedFrame()`).
+- Evidence runs through `./build.ps1` and `./test.ps1` via the normal repo
+  graph, not branch-only lanes.
+
+## Review Red Flags
+
+- A Common project directly references a feature module without an
+  explicit architecture decision.
+- Preview-only code launched from product UI without a feature gate.
+- Tests manually call `OnPropertyChanged(...)`, `ShowRecord()`, or similar
+  instead of proving the real broadcast/wiring path.
+- The active Avalonia path drives hidden legacy rendering/menu
+  infrastructure (see the hub skill's hard rules).
+- Sleep-based or timing-sensitive UI tests.
+- Claims of accessibility, localization, IME, or keyboard parity without
+  executable evidence (see the hub skill's
+  `references/parity-evidence.md` §"Evidence language").
+
+## Handoff
+
+Report Avalonia docs consulted, tests run, remaining prototype gaps,
+whether the change is product-facing or preview-only, and how the live
+wiring path was validated for each affected host. For parity work, say
+whether visual evidence is control-level headless capture or live desktop
+capture, and which automation identities were assigned.
+
+## Keep This Skill Current
+
+When a control pattern, headless-test technique, or Avalonia API gotcha
+proves out (or a pointer above goes stale), update this skill in the same
+PR — and route durable architecture lessons through the protocol in
+`fieldworks-winforms-to-avalonia-migration/references/lessons-learned.md`.

.claude/skills/fieldworks-localization-review/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: fieldworks-localization-review
+description: "Review or change FieldWorks user-facing strings: .resx resources, localization keys, the StringTable lane for field labels, Crowdin-facing assets, and localization-sensitive automation metadata. Use whenever a change adds or edits any user-visible text in WinForms or Avalonia, adds a new UI project, touches resource files, or claims localization parity — even for a single new label or error message."
+---
+
+# FieldWorks Localization Review
+
+## Use This For
+
+- Product-facing text in WinForms, Avalonia, settings UI, dialogs,
+  validation messages, fallback or unsupported-surface text, and promoted
+  preview paths.
+- `.resx` additions or changes, localization key flow, and Crowdin-sensitive
+  resource updates.
+- Automation metadata where `Name`, tooltip, or label is localized but
+  stable `AutomationId` must remain nonlocalized.
+
+## The Two Lanes (Avalonia surfaces)
+
+1. **Field labels** come from layout data and resolve through the legacy
+   StringTable lane (`XmlUtils.GetLocalizedAttributeValue`,
+   `strings-{locale}.xml`) at render time. The view-definition IR carries a
+   `LocalizationKey` per node; never bake English label text into the IR or
+   region model.
+2. **Product messages** (Save, Cancel, validation errors, unsupported-row
+   text) live in `Src/Common/FwAvalonia/FwAvaloniaStrings.resx` with
+   translator comments; accessor class `FwAvaloniaStrings.cs`; key coverage
+   locked by tests in
+   `Src/Common/FwAvalonia/FwAvaloniaTests/RegionEditingTests.cs`.
+
+## Required Checks
+
+- Product-facing user-visible strings live in `.resx` or the established
+  localization mechanism; preview-only hardcoded text stays clearly
+  preview-only.
+- New UI mode labels, fallback or unsupported messages, validation errors,
+  and diagnostics are localized before a product path is exposed.
+- Stable `AutomationId` and other selectors remain nonlocalized; localized
+  names, tooltips, and labels may vary by locale.
+- Resource keys and files align with existing Crowdin and repo conventions.
+- New SDK-style csprojs declare `<RootNamespace>` explicitly — the Crowdin
+  satellite-assembly build
+  (`Build/Src/FwBuildTasks/Localization/ProjectLocalizer.cs`) fails
+  without it.
+- If localization parity is claimed, tests or evidence cover the localized
+  path and confirm selectors do not depend on localized text. English on
+  the Avalonia surface where legacy shows translations is a parity
+  failure, not cosmetics.
+
+## Review Red Flags
+
+- Hardcoded English text in product C#, XAML, or product-facing
+  preview-promotion paths.
+- Field labels rendered raw from the IR without StringTable resolution.
+- Tests or automation selectors depending on localized labels when stable
+  IDs exist or are required.
+- A product route reusing preview-only placeholder text.
+- Localization claims without resource updates or without identifying
+  remaining hardcoded strings.
+
+## Handoff
+
+List the resource files or keys touched, remaining hardcoded product
+strings, automation identity strategy, and whether localized behavior has
+executable evidence or is still pending.
+
+## Keep This Skill Current
+
+When a new localization lane, Crowdin constraint, or resource convention
+appears (or a gap like the `<RootNamespace>` one is found), record it here
+in the same PR; route durable lessons through
+`fieldworks-winforms-to-avalonia-migration/references/lessons-learned.md`.

.claude/skills/fieldworks-managed-netfx-review/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: fieldworks-managed-netfx-review
+description: "Review or change FieldWorks managed C# code that crosses the .NET Framework 4.8 / C# 7.3 vs SDK-style net8 boundary: project files, language-feature compatibility, test discovery across both runtimes, UI-thread marshaling, and deterministic disposal. Use whenever a change touches a .csproj, adds C# to an unfamiliar project, moves code between net48 and net8 projects, or changes test runners — even if the compile passes locally."
+---
+
+# FieldWorks Managed NetFx Review
+
+## Compatibility Split
+
+- Legacy product code is .NET Framework 4.8 and C# 7.3 unless a project
+  explicitly targets modern .NET. The compiler will not always save you:
+  check the project's `LangVersion`/target before writing modern syntax.
+- New Avalonia modules may target `net8.0-windows`; do not leak C# 8+
+  syntax or net8-only APIs into net48 projects. Note that
+  `Src/Common/FwAvalonia/` itself is consumed from net48 hosts — verify a
+  project's actual target rather than assuming Avalonia ⇒ net8.
+- Legacy `.csproj` files require explicit source inclusion; SDK-style
+  projects glob by default. A file added on disk is not necessarily in the
+  build.
+- SDK-style projects need an explicit `<RootNamespace>` for the Crowdin
+  satellite-assembly build (see `fieldworks-localization-review`).
+
+## Required Checks
+
+- User-visible strings use `.resx` patterns where product-facing.
+- UI and async code marshals to the correct UI thread (via `IUiScheduler`
+  in region code) and does not use sync-over-async.
+- Disposable WinForms/GDI/LCModel/test resources are owned and disposed
+  deterministically; region code follows the `IRegionLifetime` rules
+  (idempotent disposal, late-callback suppression, event unsubscribe).
+- Test discovery changes are validated across both net48 and net8 test
+  assemblies.
+- Use repo scripts for evidence: `./build.ps1` and `./test.ps1` — never
+  bare `dotnet build` conclusions.
+
+## Review Red Flags
+
+- Nullable annotations, records, file-scoped namespaces, switch
+  expressions, or `using var` in net48/C# 7.3 projects.
+- Broad project/test-runner changes justified only by one local test
+  passing.
+- Hardcoded Debug paths or absolute repo assumptions in tests.
+- Skipped tests used as evidence of covered behavior.
+- A new project added to disk but missing from `FieldWorks.proj`
+  (traversal build) or `FieldWorks.sln` (IDE discovery).
+
+## Handoff
+
+Report target frameworks touched, project-file implications, test
+commands/results, and any remaining compatibility risks.
+
+## Keep This Skill Current
+
+When a new cross-target pitfall, project-file gotcha, or runtime
+difference bites a migration, add it here in the same PR; route durable
+lessons through
+`fieldworks-winforms-to-avalonia-migration/references/lessons-learned.md`.

.claude/skills/fieldworks-migration-scope-review/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: fieldworks-migration-scope-review
+description: "Review the scope and evidence claims of large FieldWorks migration PRs, OpenSpec changes, and foundational branches. Use when sizing or splitting a branch, judging draft-PR readiness, verifying that checked tasks match their evidence, or whenever a reviewer or author asks whether a migration PR is too big, mixed, or trustworthy."
+---
+
+# FieldWorks Migration Scope Review
+
+## Review Posture
+
+Treat foundational migration PRs as architecture and evidence packages.
+The main question is whether reviewers can trust the scope, claims, and
+validation boundary.
+
+## Required Checks
+
+- Scope review is branch-relative: compare `main..HEAD` or the merge-base
+  diff, not calendar-time commit lists. Same-day commits already on `main`
+  are not branch scope.
+- Compare PR title/body/tasks against the actual diff.
+- Classify files as plan/spec, characterization test, infrastructure,
+  prototype, product behavior, or unrelated change.
+- When product or global UI wiring appears, trace preview-vs-product
+  routing and host/listener wiring separately from plan/test changes
+  (apply `fieldworks-ui-wiring-review`).
+- Verify checked tasks match evidence language; downgrade claims when
+  evidence says substitute, placeholder, skipped, future, or partial —
+  the taxonomy is defined in
+  `fieldworks-winforms-to-avalonia-migration/references/parity-evidence.md`
+  §"Evidence language".
+- Confirm validation gates are explicit: OpenSpec validation
+  (`openspec validate <change> --strict`), targeted tests, normal
+  `./build.ps1` and `./test.ps1` coverage for Avalonia, and
+  `CI: Full local check` when ready.
+
+## Split Triggers
+
+- Product-visible behavior appears in a planning/test PR.
+- Branch-only diff mixes product-visible wiring with planning/test/docs/
+  prototype work.
+- Common infrastructure directly depends on the first feature module
+  without an explicit decision.
+- Test-runner/build graph changes are mixed with UI migration work.
+- Unrelated behavior changes require their own review context.
+
+## Review Red Flags
+
+- A draft PR so broad that each reviewer must reverse-engineer intent.
+- Scope complaints based on "commits made today" instead of the
+  branch-only diff against `main`.
+- Evidence stale after rebase or differing from visible CI state.
+- A prototype wired as if it were a product feature.
+- Skill/playbook updates from the migration retrospective missing from a
+  PR that completed a migration phase (see the hub skill's workflow
+  step 10) — institutional knowledge is part of the deliverable.
+
+## Handoff
+
+Lead with blockers, then list what to remove, split, reword, or validate
+before review. Call out false scope signals separately from real
+branch-only scope problems.
+
+## Keep This Skill Current
+
+When a new split trigger, evidence-language term, or scope failure mode
+shows up in a real review, add it here in the same PR; route durable
+lessons through
+`fieldworks-winforms-to-avalonia-migration/references/lessons-learned.md`.

.claude/skills/fieldworks-semantic-render-parity/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: fieldworks-semantic-render-parity
+description: "Capture or review FieldWorks parity evidence: semantic snapshots, render/visual baselines, layout parity, failure artifacts, XML view definitions, and the Avalonia presentation IR. Use whenever a task creates or evaluates snapshot tests, screenshot baselines, view-definition compilation output, or any claim that an Avalonia surface matches its WinForms predecessor."
+---
+
+# FieldWorks Semantic Render Parity
+
+Shared definitions (Path 3 bundle, evidence lanes, artifact naming) live in
+`fieldworks-winforms-to-avalonia-migration/references/parity-evidence.md`.
+This skill covers how to build and review the snapshots themselves.
+
+## Snapshot Discipline
+
+Semantic snapshots preserve behaviorally meaningful identity and omit
+incidental layout noise. The snapshot is the anchor artifact of a parity
+bundle: when visual evidence diverges, the snapshot explains whether the
+cause is the XML import, slice filtering, editor registry, or rendering.
+
+## Include
+
+- Stable node ID and source layout/part identity.
+- Which route produced the artifact (`Avalonia`, legacy fallback, or
+  blocked state) when a scenario can run through multiple hosts.
+- Object/class binding, field/flid binding, editor kind, writing-system
+  metadata, visibility, ghost state, expansion, focus order, localization
+  key, and accessibility identity.
+- Unsupported construct diagnostics with enough path context to fix the
+  source layout.
+
+## Exclude Or Normalize
+
+- Pixel bounds, transient generated names, timestamps, machine paths,
+  culture-dependent ordering, and realized-control counts unless the test
+  explicitly owns them.
+
+## Canonical Examples
+
+- IR model and snapshot projection:
+  `Src/Common/FwAvalonia/ViewDefinition/ViewDefinitionModel.cs`
+- Snapshot/parity tests:
+  `Src/Common/FwAvalonia/FwAvaloniaTests/RegionViewingParityTests.cs`,
+  `ViewDefinitionTests.cs`, `BrowseAndCanonicalJsonTests.cs`,
+  `Path3BundleTests.cs`
+- Import coverage tracking: `LayoutImportCoverageTests.cs` and
+  `Src/Common/FwAvalonia/ViewDefinition/LayoutImportCoverage.cs`
+- Visual/density evidence: `VisualParityAndDensityTests.cs`
+
+## Render Evidence
+
+- Pixel/render tests need deterministic fixtures, clear thresholds, and
+  failure artifacts reviewers can inspect (classified failure summary, not
+  a raw diff image).
+- A semantic snapshot is not a substitute for visual/render parity when
+  typography, density, wrapping, or native rendering seams are under
+  review — and vice versa. One lane per axis; see parity-evidence.md §2.
+- Control-level Avalonia visual evidence may come from Avalonia.Headless
+  rendered frames when the scenario is explicitly control-scoped; desktop
+  workflow/accessibility claims still need live-window evidence.
+
+## Review Red Flags
+
+- A preview-only or lossy route presented as if it proved product parity.
+- Placeholder metadata presented as real binding or writing-system parity.
+- Snapshot tests updating large JSON blobs without a small behavioral
+  explanation of what changed and why.
+- Cache invalidation tests that depend on sleeps or filesystem timestamp
+  luck.
+- A new layout construct silently dropped by the importer instead of
+  producing a diagnostic node and a coverage-tracking entry.
+
+## Handoff
+
+State whether evidence is semantic, visual, accessibility/workflow, or
+performance parity, and identify remaining unproven axes. When a Path 3
+bundle is used, name each artifact and which lane it proves.
+
+## Keep This Skill Current
+
+When snapshot fields, normalization rules, or fixture patterns change, or
+a new artifact type joins the bundle, update this skill and
+parity-evidence.md together in the same PR; record durable lessons via
+`fieldworks-winforms-to-avalonia-migration/references/lessons-learned.md`.