backlog management

specs/implemented/S7-review-signals.txt

@@ -0,0 +1,54 @@
+DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/model/scheduling/GroupRequirement.java:3 recordComponents=2 (manual design review)
+DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/model/scheduling/SchedulingInput.java:5 recordComponents=4 (manual design review)
+DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/model/scheduling/SchedulingResult.java:7 recordComponents=2 (manual design review)
+DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/DancerRequest.java:8 recordComponents=2 (manual design review)
+DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/DancerView.java:6 recordComponents=3 (manual design review)
+DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/DayPartRequest.java:7 recordComponents=2 (manual design review)
+DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/DayPartView.java:9 recordComponents=3 (manual design review)
+DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/ErrorView.java:6 recordComponents=1 (manual design review)
+DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/GroupRequest.java:12 recordComponents=5 (manual design review)
+DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/GroupView.java:13 recordComponents=7 (manual design review)
+DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/SchedulingView.java:3 recordComponents=2 (manual design review)
+DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/SchoolRequest.java:5 recordComponents=1 (manual design review)
+DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/SchoolView.java:11 recordComponents=5 (manual design review)
+DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/ShowRequest.java:13 recordComponents=3 (manual design review)
+DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/ShowView.java:13 recordComponents=4 (manual design review)
+DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/Group.java:9 recordComponents=8 (manual design review)
+DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/GroupDetails.java:9 recordComponents=5 (manual design review)
+DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/ImportPreview.java:3 recordComponents=6 (manual design review)
+DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/Part.java:9 recordComponents=3 (manual design review)
+DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/Performance.java:10 recordComponents=4 (manual design review)
+DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/Person.java:5 recordComponents=3 (manual design review)
+DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/SchoolSnapshot.java:27 recordComponents=7 (manual design review)
+DESIGN agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/Trainer.java:3 recordComponents=2 (manual design review)
+REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/model/DanceGroup.java:18 fanOut=16.0
+REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/model/DanceSchool.java:16 fanOut=16.0
+REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/DanceGroupResource.java:28 fanOut=21.0
+REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/DanceSchoolResource.java:27 fanOut=20.0
+REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/DancerResource.java:27 fanOut=20.0
+REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/SchoolSnapshotResource.java:26 fanOut=25.0
+REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/ShowResource.java:32 fanOut=25.0
+REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/rest/apimodel/GroupView.java:21 parameters=7.0
+REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/SchoolManagementService.java:102 cyclomatic=8.0
+REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/SchoolManagementService.java:282 executableLines=33.0
+REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/SchoolManagementService.java:282 parameters=5.0
+REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/SchoolManagementService.java:35 fanOut=35.0
+REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/SchoolManagementService.java:35 publicMethods=28.0
+REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/SchoolSnapshot.java:136 executableLines=37.0
+REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/SchoolSnapshot.java:174 executableLines=35.0
+REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/SchoolSnapshot.java:27 fanOut=29.0
+REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/SchoolSnapshot.java:35 parameters=7.0
+REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/SchoolSnapshot.java:42 executableLines=41.0
+REVIEW agiledancers-be/src/main/java/nl/agilecc/agiledancers/solver/OrToolsSchedulingEngine.java:20 fanOut=17.0
+REVIEW agiledancers-be/src/test/java/nl/agilecc/agiledancers/SchedulingTest.java:29 fanOut=22.0
+REVIEW agiledancers-be/src/test/java/nl/agilecc/agiledancers/SchoolManagementResourceTest.java:123 executableLines=44.0
+REVIEW agiledancers-be/src/test/java/nl/agilecc/agiledancers/SchoolManagementResourceTest.java:168 executableLines=38.0
+REVIEW agiledancers-be/src/test/java/nl/agilecc/agiledancers/SchoolManagementResourceTest.java:26 executableLines=39.0
+REVIEW agiledancers-be/src/test/java/nl/agilecc/agiledancers/SchoolSnapshotResourceTest.java:16 executableLines=40.0
+REVIEW agiledancers-be/src/test/java/nl/agilecc/agiledancers/SchoolSnapshotTest.java:30 fanOut=19.0
+REVIEW agiledancers-be/src/test/java/nl/agilecc/agiledancers/SchoolSnapshotTest.java:56 executableLines=32.0
+REVIEW agiledancers-be/src/test/java/nl/agilecc/agiledancers/SnapshotCollectionsTest.java:26 fanOut=22.0
+REVIEW agiledancers-be/src/test/java/nl/agilecc/agiledancers/service/SchedulingServiceTest.java:28 fanOut=28.0
+REVIEW agiledancers-be/src/test/java/nl/agilecc/agiledancers/service/SchedulingServiceTest.java:29 executableLines=32.0
+REVIEW agiledancers-be/src/test/java/nl/agilecc/agiledancers/service/SchedulingServiceTest.java:62 executableLines=38.0
+WAIVER agiledancers-be/src/main/java/nl/agilecc/agiledancers/service/model/Group.java:19 parameters=8.0 Maintainer approved in the S7 implementation conversation: preserve the eight-component version-2 JSON shape while defensively copying styles and dancerIds.

specs/implemented/S7-validation.md

@@ -0,0 +1,125 @@
+# S7 implementation and validation evidence
+
+Status: IN_REVIEW — implementation complete; awaiting project review.
+Date: 2026-10-30. Environment: Ubuntu amd64, OpenJDK 25.0.4.1, Maven 3.9.16.
+
+## Delivered changes
+
+Enforcement/configuration: root coding standards and agent discovery instructions;
+project review companion (upstream skills unchanged); individually selected
+Checkstyle 12.3.1 checks; PMD/CPD 7.28.0 with targeted measurements and regression
+fixtures; JaCoCo 0.8.14 with exact line-count gates; verify integration; Docker
+build inputs; CI instrumentation, merge and diagnostic retention. No broad
+standards/coverage exclusions or unrelated rule bundles were introduced.
+
+Migration: explicit imports and visibility, required finality and explicit types;
+an explicit collaborator constructor for scheduling tests while preserving CDI field injection and the public no-argument constructor; smaller snapshot-restoration,
+import-rebuilding, solver and validation methods; smaller HTTP test helpers;
+null-tolerant defensive collection copies for records, including both levels of
+solver assignments. Existing entity classes retain their mutation, Lombok and
+framework contracts. API paths, payloads, snapshot version and persistence behavior
+are unchanged. Enforcement and migration can be reviewed separately by path.
+
+## Scope, tools and measurements
+
+58 handwritten production files and 9 handwritten test files are checked.
+Generated target output, frontend code and Java helpers outside the backend are
+outside that standards scope. All handwritten production packages participate in
+coverage, including DTOs and configuration. JaCoCo's generated-member filtering is
+used; no handwritten class/package exclusions are configured.
+
+See CODING_STANDARDS.md for complete targets, strict thresholds, algorithm options,
+manual rules, scope and standalone commands. The full current metrics report is
+`agiledancers-be/target/standards/report.txt`. Production CPD currently reports
+**0%** duplicated code lines at its 100-token minimum. Test duplication is not gated.
+
+The selected PMD finality rules complement custom checks. PMD cyclomatic and
+cognitive visitors are scoped explicitly: lambdas contribute, nested/local type
+methods are independent, and no aggregate class complexity gate is introduced.
+Resolved collaborator identity includes qualifier values/defaults and inherited
+generic type substitution. Exact metric waivers are supported and regression tested;
+`tooling/standards/waivers.tsv` records the sole approved waiver: the exact
+eight-parameter Group constructor needed to preserve its version-2 JSON shape.
+
+## Reproducible validation
+
+Set JAVA_HOME to JDK 25 and run from the repository root.
+
+| Command/check | Result |
+| --- | --- |
+| `mvn -Dformat.mode=check clean verify` | Passed: 38 backend tests, 19 checker tests, standards checks and the exact backend coverage gate. |
+| `mvn -pl agiledancers-be package -DskipTests` | Passed; Quarkus packaged app successfully produced and subsequently exercised by Playwright. |
+| `mvn -f tooling/standards/pom.xml test exec:java` | 19 checker tests passed; no unwaived blocking violations. |
+| `java tooling/coverage/Coverage.java agiledancers-be/target/site/jacoco/jacoco.xml` | Clean backend-only line gate passed: 791 covered / 818 total = 96.69926650366749%. |
+| `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/opt/google/chrome/chrome npm run e2e` in frontend | Both browser tests passed against the packaged instrumented backend. |
+| Pinned CLI `dump --address 127.0.0.1 --destfile agiledancers-be/target/playwright.exec` | Successfully collected execution data from the agent's TCP server. |
+| `mvn -pl agiledancers-be jacoco:merge@combined jacoco:report@combined-report exec:exec@combined-coverage` | Passed with matching clean-build application classes: combined 791/818 lines, 96.69926650366749%. |
+| `java ci/Ci.java test` | 17 CI orchestration tests passed. |
+| `git diff --check` | Passed. |
+
+Both local and combined branch reports contain 195 covered / 257 total branches
+(75.87548638132296%); branches have no blocking percentage. Browser coverage is
+successfully collected and merged, but does not add uncovered lines in this run.
+Local and combined HTML/XML/CSV reports are under `agiledancers-be/target/site`.
+Execution data is in `target/jacoco.exec`, `target/playwright.exec` and
+`target/jacoco-combined.exec` within the backend module. CI copies these reports,
+execution data and checker results into its retained diagnostics. Local validation
+exercised collection and merge; a remote Gitea publication run was not performed.
+
+The checker fixtures cover strict complexity, length, parameter, nesting,
+inheritance and dependency boundaries; implicit/compact record constructors;
+lambda/nested-type scope; comments/brace lines; distinct type fan-out; nontrivial
+accessors; qualifiers, repeated and inherited injection; exact waivers; parser
+failure diagnostics; report-only behavior; CPD occurrence/overlap accounting and
+test exclusion; and the unrounded 80% line gate, including a near miss.
+
+## Retained review signals
+
+`S7-review-signals.txt` records the current individual REVIEW and DESIGN entries.
+The following assessment covers every retained review-signal group. The approved
+constructor waiver is documented separately below.
+
+| Signal/location | Assessment and reason retained |
+| --- | --- |
+| DanceGroup and DanceSchool fan-out 16 | Domain collection/entity references and explicitly used Lombok annotations are intrinsic to these mutable aggregates. Converting them to records would break their mutation/inheritance contracts. |
+| Five REST resources, fan-out 20–25 | HTTP annotations, response/request types and service/domain mapping account for the references. These are thin adapters; splitting them to reduce annotation counts would obscure endpoint ownership. |
+| GroupView and SchoolSnapshot compact constructors, 7 parameters | Their components preserve existing JSON contracts. Constructors only protect collections and are within the allowed constructor limit. |
+| SchoolManagementService fan-out 35, public methods 28 | One shared synchronization boundary owns in-memory aggregate writes and scheduling revisions. Splitting state/locks needs its own concurrency design; the class passes blocking length/dependency limits. |
+| validateAssignments cyclomatic 8 | Independent input/result guards and required-appearance validation are explicit and tested; per-part validation has already been extracted. It remains below the blocking limit. |
+| updateShow, 33 lines and 5 parameters | Retains assignments by matching daypart keys before replacing the aggregate. Keeping the transaction visible and preserving its existing signature is preferable to artificial wrappers; both blocking limits pass. |
+| SchoolSnapshot fan-out 29; of 41 lines, restoreGroups 37, restoreShows 35 | Each method performs one graph conversion phase. Explicit type/reference checks protect imported data and preserve assignment identity. Refactoring has removed the over-limit monolithic restore method. |
+| Solver fan-out 17 | OR-Tools types are confined to this adapter and its dedicated helpers. Further indirection would spread solver details without improving the domain boundary. |
+| SchedulingTest, SchoolSnapshotTest, SnapshotCollectionsTest and SchedulingServiceTest fan-out | These behavior tests intentionally exercise multiple collaborating models, services, ports, exceptions and assertions. Production architecture remains covered separately by ArchUnit. |
+| HTTP, snapshot and scheduling test methods at 32–44 lines | Arrange/action/assert and try/finally cleanup remain together. Repeated setup was extracted where methods exceeded 50 physical code lines; retained methods pass all blocking limits. |
+| All DESIGN record-component entries | Request/view/snapshot/domain records model existing named contracts; their sizes are not automatically gated. Mutable components are copied, including both Group lists under its approved constructor waiver. Framework-backed mutable entities remain classes. |
+
+## Approved compatibility decisions
+
+The maintainer approved both proposals in the S7 implementation conversation:
+
+1. `GroupDetails` groups category, type, age bounds and styles. The Java signatures
+   of `DanceGroupService.add`, `SchoolManagementService.createGroup` and
+   `updateGroup` now take 3, 2 and 3 parameters respectively. All callers were
+   migrated. REST endpoints, JSON payloads and snapshot version remain unchanged.
+   The record copies its styles, and service construction takes a mutable copy
+   for the domain group; regression coverage verifies later style edits still work.
+2. The explicit eight-component `service.model.Group` constructor defensively
+   copies styles and dancer IDs while preserving null values for existing import
+   validation. Its sole waiver matches the fully resolved constructor signature,
+   metric and exact retained value 8. The agreement and reason are recorded in
+   `tooling/standards/waivers.tsv` and the result remains visible as `WAIVER`.
+
+There are no parameter waivers for the three service methods, blanket suppressions
+or weakened thresholds. The completed specification resides in `specs/in_review`.
+
+## Review fixes
+
+The review fixes enforce finality for assign-once pattern bindings, including
+`instanceof`, switch and record-deconstruction bindings, while allowing reassigned
+bindings and inferred record-pattern types. Trivial-accessor detection now uses
+AST statements and resolved field/parameter references, so comments do not change
+public-method counts. Accessors with calls, extra statements or compound
+assignments still count. Two regression tests cover these cases.
+
+After these fixes, JDK 25 `mvn -B -ntp -Dformat.mode=check verify` passed with
+38 backend tests, 19 checker tests and backend line coverage of 791/818 (96.70%).

specs/implemented/S8-formatting-evidence.md

@@ -0,0 +1,96 @@
+# S8 implementation evidence
+
+Measured on 2026-10-30 on Linux x86_64 (kernel 7.0.0-38-generic), AMD Ryzen 7
+7730U, 16 logical CPUs; Ubuntu OpenJDK 25.0.4.1, Maven 3.9.16. These are local
+wall-clock measurements, not universal performance guarantees.
+
+## Integration and scope
+
+- exec-maven-plugin 3.6.3; OpenRewrite core 8.63.4; Palantir Java Format 2.101.0.
+- Custom `Format.PalantirRecipe` processes OpenRewrite PlainText source files
+  using Palantir's `formatSourceAndFixImports`, Palantir style, `formatJavadoc(false)`.
+  No Java type attribution, OpenRewrite Java parser or AutoFormat is involved.
+- 73 maintained Java files: 65 backend production/test files, 7 CI/runner helpers,
+  and the formatter helper. Recursive discovery excludes generated build output.
+- Root validate executes before compilation; compile/test/verify/install all reach
+  validate. CI explicitly passes check mode to clean verify. Standalone commands
+  run only the root exec execution and do not compile the backend.
+- Bootstrap was first executed with neither Palantir nor OpenRewrite in the local
+  Maven repository. The helper is source-launched, with dependencies supplied by
+  Maven's plugin classpath. There is no project recipe artifact to preinstall.
+  The isolated regression fixture also has no compiled adapter or backend module.
+
+## Correctness
+
+- Full `mvn -B -ntp clean verify` passed after formatting: 33 backend tests,
+  zero failures/errors/skips. Both benchmark clean verifications also pass.
+- `java ci/Ci.java test`: 17 passed, including assertion of the exact check-only
+  Maven invocation and that Maven failure removes the success marker and prevents
+  image build/publication.
+- `python3 tooling/format/test.py` checks an isolated source-launcher checkout:
+  read-only check failure with path and apply command; native unused-import
+  removal; UTF-8 non-ASCII preservation; check/apply agreement; second uncached
+  check with no differences; malformed Java fails with its path and leaves the
+  source bytes unchanged; a newly introduced file cannot evade the content cache.
+- All current Java files have been processed by the real engine on JDK 25,
+  including records, switch expressions/multiple labels, pattern instanceof,
+  lambdas and source-launcher CI classes. Tests compile/run the resulting sources.
+  This demonstrates the syntax used here, not every possible Java 25 construct.
+- Palantir uses javac internals (explicit JVM exports are in the root POM) and its
+  modern AST visitor. Recheck formatter compatibility when upgrading the JDK.
+  Compact source files / instance main methods are a known upstream limitation
+  ([upstream issue](https://github.com/palantir/palantir-java-format/issues/1602));
+  they are not used here. Unsupported future syntax fails, rather than being
+  silently excluded. Extra Markdown/Javadoc formatting is disabled.
+- The initial Java rewrite is committed separately from integration changes;
+  its only transformations are the formatter's native output and import handling.
+
+## Performance
+
+`python3 tooling/format/benchmark.py` runs sequentially, with normal dependencies
+and OS filesystem caches warm. Each configuration receives a compile warmup.
+The baseline temporarily removes the entire exec plugin declaration from the
+root POM, then restores its original bytes before the formatting build. Therefore
+these comparisons include plugin loading, dependency resolution, JVM launch,
+source-launcher compilation, hashing, cache IO and recipe execution. They do not
+compare only the inner formatter function or a skipped plugin against itself.
+
+The successful-content cache is warm for unchanged builds; it is part of the
+integration. Changed/new files are processed by Palantir. Clean builds remove the
+cache and process every maintained Java file. Each run's stdout and elapsed time
+are saved under `target/`; the benchmark restores the root POM and changed helper.
+
+| Repeated compile | Baseline (s) | Integration (s) | Added overhead (s) |
+| --- | ---: | ---: | ---: |
+| 1 | 4.887 | 6.414 | 1.527 |
+| 2 | 4.821 | 5.964 | 1.143 |
+| 3 | 4.559 | 6.024 | 1.465 |
+
+Maximum observed added overhead: **1.527 seconds**, below the agreed three-second
+limit. Baseline compile warmup: 5.307 s; integration warmup: 7.604 s.
+
+The changed-file case appends a newline to `ci/runner/WaitForDocker.java`, then
+runs `mvn -B -ntp compile`: **5.506 s**, successful; Palantir processes that
+changed file. The script restores its original bytes afterward.
+
+Clean baseline `mvn -B -ntp clean verify`: **24.797 s**. Clean integration
+`mvn -B -ntp -Dformat.mode=check clean verify`: **27.747 s**, all 73 files
+processed, no differences, all tests pass. The three-second criterion applies
+to repeated unchanged builds, not the clean-build comparison.
+
+### First-use downloads (separate measurement)
+
+A disposable root POM with the same pinned plugin/dependencies and an empty
+`-Dmaven.repo.local` replaces only the Java executable with `/usr/bin/true`.
+Thus dependency resolution runs without compiling the launcher or executing the
+formatter/application. Command:
+`mvn -N -B -ntp -Dmaven.repo.local=<empty-temp-repository> org.codehaus.mojo:exec-maven-plugin:3.6.3:exec@format`.
+Cold resolution took **9.041 s**; the same command with that repository populated
+took **1.826 s**. The **7.215 s** cold-versus-warm difference represents first-use
+network/repository population overhead in this environment, separately from the
+warm-cache build measurements above. Cold timing also includes root POM/BOM and
+plugin bootstrap resolution; it is not reported as pure formatter execution.
+Reproduce with `python3 tooling/format/benchmark-downloads.py` (Linux, network
+access). The initial real source-launcher bootstrap/check also successfully
+processed all files; its expected failure listed formatting differences, rather
+than a missing project recipe or parser/bootstrap error.