[CatarinaGamboa]

Closes #518
Closes #519

What and why

Changes to the state hints in StateHints (display and choice of hints only; the VC, verdict and category are unchanged):

1. Call sequences name only the state they lead to (State hints: name only the state the call leads to #519): Call S before this call; afterwards <state>. The "from" part is gone, since the Found already shows it. In A1_09 it listed every state of the set (from display(host) == notDisplayable or display(host) == displayable). "Afterwards" is the machine's after state for the changed sets, so the hint only states what the machine computes after the calls, and no != is turned into ==. The value form from Show states of named sets by their set in state hints and declared-here #517 stays (markState(buffered) == marked). Classes with no named set read afterwards f is open.
2. A deciding argument is written as the call (State hints: name only the state the call leads to #519): when a step's condition is param == c for the method's only parameter, and c names no variable, the step is written wParam.setCompressionMode(ImageWriteParam.MODE_EXPLICIT). Any other condition keeps r.set(int lo, int hi) with lo < hi.
3. No GUARD hint when a CALL_SEQUENCE hint exists (Drop the guard hint when a call-sequence hint exists, and reword it #518). Wrapping the call in the check skips it in exactly the failing case. In A1_09 the verifier accepts that fix and the study grader marks it INCORRECT. Before, the guard was dropped only for a single known state. The unknown-state hints (A1_56) do not change: its guard stays, since it has no call sequence and the guard is the reference fix.
4. Guard wording (Drop the guard hint when a call-sequence hint exists, and reword it #518): Guard this call with if (<check>); inside it, <state>. This replaces "when it returns false", which was ambiguous next to !host.isDisplayable().
5. AVAILABLE_CALLS ("can call") is dropped when any other hint is given (State hints: name only the state the call leads to #519). FINAL_STATE is unchanged.

Study tasks (CLI, before = main, after = this branch)

Each task still gives exactly one error, on its reportedLine. A2_10, A2_04, practice and practice2 are unchanged.

A1_38

before:
  - Call buffered.mark(int) before this call to move buffered from markState(buffered) == unmarked to markState(buffered) == marked
  - When stream(buffered) == open and markState(buffered) == unmarked, buffered can call: read(), read(byte[], int, int), skip(long), available(), mark(int), ...
after:
  - Call buffered.mark(int) before this call; afterwards markState(buffered) == marked

A1_01

before:
  - Call wParam.setCompressionMode(int mode) with mode == ImageWriteParam.MODE_EXPLICIT before this call to move wParam from compression(wParam) == compressionNotExplicit to compression(wParam) == compressionExplicit
  - When tiling(wParam) == tilingNotExplicit and compression(wParam) == compressionNotExplicit, wParam can call: setTilingMode(int), setCompressionMode(int) (and possibly others)
after:
  - Call wParam.setCompressionMode(ImageWriteParam.MODE_EXPLICIT) before this call; afterwards compression(wParam) == compressionExplicit

A1_09

before:
  - Call host.dispose() before this call to move host from display(host) == notDisplayable or display(host) == displayable to display(host) == notDisplayable
  - Call host.removeNotify() before this call to move host from display(host) == notDisplayable or display(host) == displayable to display(host) == notDisplayable
  - Guard this call with if (!host.isDisplayable()): when it returns false, display(host) == notDisplayable
  - When display(host) == notDisplayable or display(host) == displayable, host can call: pack(), dispose(), addNotify(), removeNotify() (and possibly others)
after:
  - Call host.dispose() before this call; afterwards display(host) == notDisplayable
  - Call host.removeNotify() before this call; afterwards display(host) == notDisplayable

host.dispose() is still the first hint. analysis/check-fixes.py --selftest --task A1_09 passes 8/8 and grades the plain dispose() fix (P01) CORRECT.

A1_56 (the guard stays)

before:
  - The state of undoManager is unknown here, and this call needs redoState(undoManager) == redoable
  - Guard this call with if (undoManager.canRedo()): when it returns true, redoState(undoManager) == redoable
after:
  - The state of undoManager is unknown here, and this call needs redoState(undoManager) == redoable
  - Guard this call with if (undoManager.canRedo()); inside it, redoState(undoManager) == redoable

IDE

Hints reach vscode-liquidjava as plain message text, so they show there with no extension change. There are no screenshots, because nothing in the extension's layout changes.

Tests

The exact-message expectations in TestStateHints are updated. Each of these fails on main: the new wording, no "can call" next to another hint, and setCompressionMode(2) / chain.pick(1) for the argument form. One case is added to the existing ErrorStateHintGuards fixture: reachableOnEveryPath, the A1_09 shape (path-dependent state, a call that reaches the needed state, a query). On main it gives a sequence, a guard and "can call"; now it gives only the sequence. The full suite passes locally (728 tests).

Open for the PM

• The unknown-state hints (anyState, used by A1_56) can also list a call sequence after the guard. Drop the guard hint when a call-sequence hint exists, and reword it #518 scopes the rule to forCall, so the guard is kept there. None of the study tasks has both.

🤖 Generated with Claude Code

[CatarinaGamboa]

Clean-code review

I audited this PR's new code only (clean-code-principles). The PM's small-PR rule takes precedence.

Fixed

• StateHints.allowedCalls: [func-few-arguments / flag argument] my first version added a boolean onlyHint parameter. Now forCall filters out AVAILABLE_CALLS itself, and allowedCalls keeps its old signature.
• StateHints.callSequence / howToReach: [core-yagni] fromAnyState existed only to print "from any state". It is removed along with the "from" part.
• StateHints.guard / callSequence: [core-dry] both built (asValues ? "" : receiver + " is ") + states. They now share isIn.

Declined

• StateHints.call(CallVariant): [core-dry] receiver + "." + simpleName + "(" ... ")" is close to guardCall. Declined: they differ in what goes in the parentheses, and a shared helper would save one line.
• argumentValue: [core-kiss] it handles only a method with one parameter. Declined: for several parameters it would have to write the others as ..., which the issue does not ask for. Those keep the with <condition> form, which is sound.

There are no SOLID or layering issues. All the wording stays in StateHints.

[CatarinaGamboa]

Codex review, round 1

No findings. Codex reran TestStateHints and every state-hint fixture through the CLI and found no actionable regression. The review loop ends here.

The full suite passes locally (728 tests).