agiledancers/specs/S7-validation.md

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, 17 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	17 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.