docs: design manual tidy capacity ownership

docs/superpowers/specs/2026-07-24-wms-manual-tidy-capacity-design.md

@@ -0,0 +1,68 @@
+# WMS Manual Tidy Dynamic Capacity Design
+
+## Goal
+
+Keep WCS as the sole owner of physical vehicle dispatch while allowing WMS to throttle manual tidy workflow creation from the current WCS vehicle snapshot and a configured concurrency ceiling.
+
+## Current Problem
+
+WMS currently pairs every new manual tidy workflow with a specific idle vehicle and stores that identifier in `alg.tidy_workflow.vehicle_id`. The generated `mydo_job` and the WMS-to-WCS contract do not contain a vehicle identifier, so WCS cannot honor that pairing and independently selects a vehicle.
+
+The current capacity calculation also subtracts active workflows from a snapshot that already contains only idle vehicles. A vehicle executing an active workflow is therefore excluded once by `idle=false` and the workflow can consume capacity a second time. This can leave an actually idle vehicle unused.
+
+## Decision
+
+1. WCS remains responsible for selecting the physical vehicle for every tidy move job.
+2. WMS no longer assigns a vehicle identifier when it creates a manual tidy workflow.
+3. The WCS snapshot remains a fail-closed dynamic admission signal, not a vehicle reservation contract.
+4. WMS adds `fortucky.algorithm.tidy-manual-max-concurrency`, defaulting to `3`, as a hard ceiling for active manual tidy workflows.
+5. WMS calculates new workflow slots as:
+
+   ```text
+   min(healthy online idle vehicles, max(0, configured maximum - active manual workflows))
+   ```
+
+6. A non-positive configured maximum disables creation of new manual tidy workflows.
+
+## Runtime Flow
+
+On every manual tidy reconciliation cycle, WMS first performs workflow recovery and confirms that the warehouse is actively in manual tidy mode. It then fetches the WCS vehicle snapshot, counts vehicles satisfying `online && healthy && idle`, reads the number of active manual tidy workflows, and applies the configured ceiling.
+
+WMS asks the planner for candidates only when at least one slot exists. It starts at most the calculated number of workflows in planner order. No candidate is paired with a snapshot row, and no `vehicle_id` update is issued. WCS later receives the ordinary move job and chooses the actual vehicle using its existing dispatch rules.
+
+## Failure Handling
+
+If the WCS snapshot URL is absent, the request fails, the response is empty, or the response cannot be parsed, the snapshot client returns an empty list. The calculated idle count is then zero, so WMS creates no new manual tidy workflows during that cycle. Existing workflows and WCS queues continue independently and can still complete.
+
+This fail-closed behavior avoids building an unbounded WCS queue when real-time fleet availability is unknown. Operators can distinguish this condition through the existing snapshot warning log.
+
+## Compatibility
+
+The existing `alg.tidy_workflow.vehicle_id` column, SQL Server index include, and diagnostic projection remain in place for schema and historical-data compatibility. Runtime code stops reading or writing the column for new manual tidy scheduling. No WCS API or database migration is required.
+
+Automatic tidy scheduling is unchanged and continues to run only in `NORMAL` mode without consulting the WCS vehicle snapshot.
+
+## Configuration
+
+`AlgorithmProperties` exposes `tidyManualMaxConcurrency` with a default value of `3`.
+
+`application.yml` binds:
+
+```yaml
+tidy-manual-max-concurrency: ${FORTUCKY_TIDY_MANUAL_MAX_CONCURRENCY:3}
+```
+
+The environment variable allows each warehouse to lower or raise the ceiling without rebuilding WMS.
+
+## Tests
+
+The implementation must prove the following behavior with tests written before production changes:
+
+1. One busy manual workflow does not consume an already-filtered idle vehicle slot twice.
+2. The configured ceiling limits new slots even when more vehicles are idle.
+3. Active workflows at or above the configured ceiling produce zero new slots.
+4. Offline, unhealthy, and busy vehicles do not produce slots.
+5. Manual scheduling starts workflows in planner order without reading or writing vehicle bindings.
+6. The default configured maximum is `3`.
+
+Focused tests must pass before running the full Maven reactor test suite and package build.