S18 Added OR Tools rules for scheduling show

docs/s18-validation.md

@@ -0,0 +1,70 @@
+# S18 implementation validation
+
+Validated on 2026-11-03 against the confirmed S18 specification.
+
+## Automated checks
+
+- JDK 25 `mvn clean verify`: passed, 52 backend tests and 19 standards-tool
+  regression tests, with no failures or skipped tests.
+- Clean backend line coverage: 1175/1215 lines, 96.70781893004116%, above the
+  exact 80% gate. No handwritten-code exclusions were introduced.
+- Frontend `npm test`: 24 tests across six files passed.
+- Frontend production build and ESLint: passed.
+- Playwright with the real REST backend: all three scenarios passed, covering school management,
+  shared memberships, automatic scheduling, manual draft editing and finalization,
+  a coach accompanying preschoolers across dates, and connection-error recovery.
+
+Focused solver tests cover showcase bookends (including extra showcases), single
+and absent showcases, changing gaps, coach exemptions, infeasibility, the strict
+priority of showcase attendance over balance, and style/age scores. Lifecycle
+and HTTP tests cover skipped empty groups, first-show-date ages, retained x after
+daypart removal, atomic structural validation, invalid drafts, final status
+invalidation, stale solver results, timeout preservation, coach identity links,
+and ordered JSON round trips including version-2 migration.
+
+## Manual standards assessment
+
+The standards report passes without new waivers. Retained review signals were
+assessed against `CODING_STANDARDS.md` and `docs/backend-review.md`:
+
+- `GroupRequirement`, `SchedulingInput`, `Performance` and `ShowView` carry six
+  or seven related snapshot/API values. Collections are defensively copied;
+  coach identity and group membership use IDs across the solver boundary.
+  The larger record shapes make the scheduling contract explicit. Other added
+  records are small. `OrderedAssignments` deliberately owns mutable OR-Tools
+  variables and arrays internally during one solve; it is not an API snapshot.
+- `ScheduleRules` has cyclomatic signals for independent configuration checks
+  and showcase cases. Each rule family is isolated in a short method and shared
+  between finalization and solver-result validation.
+- `ShowSchedules` retains branching for nullable initial settings, retained x,
+  and structural draft validation. It stages complete replacement lists before
+  mutation and uses the existing aggregate lock. It separates schedule lifecycle
+  from the already broad `SchoolManagementService` aggregate owner.
+- The aggregate owner's fan-out and public-method signals are retained for its
+  repository and transaction ownership. Scheduling-input preparation, coach
+  identity operations, lifecycle rules and scoring reside in separate focused
+  classes. Its new revision operation invalidates final status as well as pending
+  solver results.
+- `SchoolSnapshot` retains orchestration size, fan-out and cognitive signals for
+  validating and reconstructing an entire graph. Import resolves coach/dancer
+  links explicitly, retains order, rejects unknown references, accepts invalid
+  assignment drafts and resets imported final status. Graph construction remains
+  staged before repository mutation.
+- REST resource fan-out is mainly endpoint annotations, request/view types and
+  domain/service collaborators. OR-Tools stays inside the solver package.
+  `SchedulingInputs` uses domain types to produce one immutable solver snapshot.
+- `OrToolsSchedulingEngine` retains a length/cognitive signal for the ordered
+  optimization stages and their feasible/optimal/timeout outcomes. Keeping the
+  incumbent and freezing only proven optima preserves strict objective priority
+  and valid results within one total deadline.
+- Solver objective helpers retain five-parameter review signals where a model,
+  variables, group pair and objective coefficient are needed. Replacing those
+  with additional transient wrapper types would obscure the constraint mapping.
+  Common adjacency penalties are algebraically removed without changing scores.
+- Test fan-out and scenario length signals reflect full HTTP/import/concurrency
+  workflows. Shared fixture setup is extracted where it aids readability; every
+  executable remains within the blocking limits.
+
+Public behavior is documented in `show-scheduling-rules.md`, the README and the
+school JSON format reference. No new standards waiver, threshold change or
+analysis exclusion is required.