fleet/fleetd
3
0
Fork 0
Code Issues 91 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

CLAUDE.md claims code-quality rules 1, 2 and 3 have build checks — only rule 5 does #773

New Issue
Open
opened 2026-10-05 13:43:57 +02:00 by ltms · 0 comments
ltms commented 2026-10-05 13:43:57 +02:00
Owner
Copy Link
Copy Source

The claim

CLAUDE.md, §Code quality, last paragraph:

Rules 1, 2, 3 and 5 have build checks, and Gitea CI runs them on every PR, so they bind members too.

What is actually there

Measured at 364b229:

grep -rln 'com.tngtech.archunit' fleetd/src/test/java   → PackageCyclesTest.java  (only file)
fleetd/pom.xml: checkstyle | pmd | spotbugs | enforcer  → no match
scripts/: any javadoc or comment gate                   → no match
.gitea/workflows/ci.yml steps                           → mvn clean install
                                                          mvn javadoc:javadoc -Ddoclint=reference
                                                          scripts/test-redeploy-fleetd.sh
                                                          mvn -Pcontract test

So:

Rule Claimed Actual
1 — a comment states the current contract only build check none
2 — a javadoc block stops at 30 lines build check none
3 — no main comment names a test class build check partial — see below
5 — no new package cycle build check yes, PackageCyclesTest (ArchUnit)

Rule 3's partial gate is CI's -Ddoclint=reference, which resolves {@link} targets. That does not cover rule 3, because rule 3's own text says why it exists: "a name inside {@code} is invisible to the compiler and rots in silence." doclint cannot see a {@code} name either. So the gate catches a different failure than the rule describes.

Why this is worth a ticket rather than a quiet edit

The sentence does more than overstate. It tells every session reading the file that three rules are already enforced, which is a reason not to check them by hand. The file is the instruction surface this repo ships, so a wrong line here is obeyed as faithfully as a right one.

The effect is visible in the current numbers. Rule 2 has no gate and there are now 64 javadoc blocks over 30 lines, the longest 235 (config/ConfigRef.java:17):

# blocks over 30 lines, counted by walking /** … */ in fleetd/src/main/java
64

Rule 3, by contrast, has improved on its own: 41 distinct test-class names in 71 comment places, and 0 of them dead, against the 44-in-76-with-2-dead the file records. So review is doing some of this work — it is just not a gate.

What to change

Two options, and they are not equivalent:

  1. Correct the sentence. Say that rule 5 has a build check, that CI's reference lint catches dead {@link} but not {@code}, and that rules 1, 2 and 3 are review obligations. This is honest and costs nothing. It also removes the only reason a reader would skip them.
  2. Build the missing checks, then the sentence becomes true. Rule 2 is the easy one — walking /** … */ blocks and failing over 30 lines is a short test, and the count it would start from is 64, so it needs a frozen baseline like PackageCyclesTest has rather than a hard zero.

Option 1 should land regardless, and first. Shipping a gate is a separate decision with a separate cost.

Note the precedent the file itself sets, two sentences earlier, for rule 4: "a rule dressed as a gate it does not have is worse than an honest review item." That is exactly this defect, and rule 4 is the only one the file describes correctly.

Related

Not a blocker for, and not blocked by, #770.

## The claim `CLAUDE.md`, §Code quality, last paragraph: > Rules 1, 2, 3 and 5 have build checks, and Gitea CI runs them on every PR, so they bind members too. ## What is actually there Measured at `364b229`: ``` grep -rln 'com.tngtech.archunit' fleetd/src/test/java → PackageCyclesTest.java (only file) fleetd/pom.xml: checkstyle | pmd | spotbugs | enforcer → no match scripts/: any javadoc or comment gate → no match .gitea/workflows/ci.yml steps → mvn clean install mvn javadoc:javadoc -Ddoclint=reference scripts/test-redeploy-fleetd.sh mvn -Pcontract test ``` So: | Rule | Claimed | Actual | |---|---|---| | 1 — a comment states the current contract only | build check | **none** | | 2 — a javadoc block stops at 30 lines | build check | **none** | | 3 — no main comment names a test class | build check | **partial** — see below | | 5 — no new package cycle | build check | yes, `PackageCyclesTest` (ArchUnit) | Rule 3's partial gate is CI's `-Ddoclint=reference`, which resolves `{@link}` targets. That does **not** cover rule 3, because rule 3's own text says why it exists: *"a name inside `{@code}` is invisible to the compiler and rots in silence."* `doclint` cannot see a `{@code}` name either. So the gate catches a different failure than the rule describes. ## Why this is worth a ticket rather than a quiet edit The sentence does more than overstate. It tells every session reading the file that three rules are already enforced, which is a reason not to check them by hand. The file is the instruction surface this repo ships, so a wrong line here is obeyed as faithfully as a right one. The effect is visible in the current numbers. Rule 2 has no gate and there are now **64 javadoc blocks over 30 lines**, the longest 235 (`config/ConfigRef.java:17`): ``` # blocks over 30 lines, counted by walking /** … */ in fleetd/src/main/java 64 ``` Rule 3, by contrast, has improved on its own: 41 distinct test-class names in 71 comment places, and **0 of them dead**, against the 44-in-76-with-2-dead the file records. So review is doing some of this work — it is just not a gate. ## What to change Two options, and they are not equivalent: 1. **Correct the sentence.** Say that rule 5 has a build check, that CI's reference lint catches dead `{@link}` but not `{@code}`, and that rules 1, 2 and 3 are review obligations. This is honest and costs nothing. It also removes the only reason a reader would skip them. 2. **Build the missing checks**, then the sentence becomes true. Rule 2 is the easy one — walking `/** … */` blocks and failing over 30 lines is a short test, and the count it would start from is 64, so it needs a frozen baseline like `PackageCyclesTest` has rather than a hard zero. Option 1 should land regardless, and first. Shipping a gate is a separate decision with a separate cost. Note the precedent the file itself sets, two sentences earlier, for rule 4: *"a rule dressed as a gate it does not have is worse than an honest review item."* That is exactly this defect, and rule 4 is the only one the file describes correctly. ## Related Not a blocker for, and not blocked by, #770.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
blocked
Cannot start until something else lands. The body says what.
 needs-live-proof
Merged and green, but never shown working on the running daemon. Not the same as done.
 ready-to-delegate
Scope, files and acceptance criteria are written. A worker can be briefed from the body alone.
 silent-default
A feature that compiles, passes tests, and ships turned off. Nine recurrences and counting.
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
agent kevin ltms
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: fleet/fleetd#773
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?