javadoc-refactorlisted

# Javadoc refactor pass A pass over code whose production types have moved and whose comments have not caught up. Stale javadoc is worse than none: it is read as a contract, and unlike a stale test it fails nothing. Write the comments in the house style: see the `javadoc-style` skill ([../javadoc-style/SKILL.md](../javadoc-style/SKILL.md)) - what earns a comment, where one goes, what never goes in, formatting. This document says *what to do and in what order*; that one says *what the result must look like*. ## Unit of work The inventory is **the files the refactor touched**, not the whole tree - and `src/main` only, since tests carry their contract in `@DisplayName` rather than in javadoc: ```bash git status --porcelain | awk '{print $NF}' | grep 'src/main/.*\.java$' | sort -u \ | while read f; do [ -f "$f" ] && echo "$f"; done > files.txt ``` Filtering by `-f` matters: a rename shows both sides, and the deleted side is still in the listing. Then classify before reading. Which files are interfaces or enums, and which have no type comment at all, is one cheap query and it decides most of the work: ```bash while read f; do kind=$(grep -m1 -oE "public (interface|enum|@interface|final class|abstract class|class|record)" "$f") printf "%-58s %-20s blocks=%s\n" "$f" "$kind" "$(grep -c '^\s*/\*\*' "$f")" done < files.txt | grep -E "interface|enum" ``` ## The two passes The order is fixed. Pass 2 is the cheap half, and doing it first buries the half that matters