docs(vcs/jit): partial diff score is not 'always lower' than the commit score (experience term is negative)

[dekobon]

Summary

The JitDiffReport docs claim the partial (diff-only) score is "always lower" than the full commit score for the same change, but the experience term is negatively signed, so a change by an experienced author can make the full commit score lower than the partial diff score.

Location

• src/vcs/jit.rs:329-335 (the # Not comparable to a commit score doc section of JitDiffReport)

Evidence

The doc states:

/// [`partial_risk_score`](JitDiffReport::partial_risk_score) sums only the
/// size and diffusion contributions, so it is **always lower** than the full
/// [`JitReport::risk_score`] for the same change would be (which also folds in
/// history, experience, and purpose).

But score() (src/vcs/jit.rs:303-315) makes the experience term strictly non-positive:

let experience = -0.10 * ln1p(f64::from(e.author_prior_commits))
    - 0.05 * ln1p(f64::from(e.author_recent_commits));
...
let total = (size + diffusion + history + purpose_term + experience).max(0.0);

score_diff_features returns partial = size + diffusion (both ≥ 0).

For a real commit with the same size + diffusion, no history, no fix/revert purpose, but an experienced author:

• full = max(0, size + diffusion + experience) with experience < 0
• partial = size + diffusion

So whenever size + diffusion + experience is still positive, full = partial + experience < partial. The full commit score is lower than the partial diff score, not higher.

This is not hypothetical — the file's own tests demonstrate both halves:

• experience_lowers_the_score (src/vcs/jit_tests.rs:162-193) asserts veteran_total < novice_total for the same change.
• The "tiny change by a very experienced author" test (src/vcs/jit_tests.rs:241-261) asserts the pre-floor sum size + diffusion + history + purpose + experience is negative.

Expected Behavior

The doc should state the two scores live on different, incomparable scales (which it already does correctly elsewhere: "The two scores live on different scales: rank diffs against other diffs, never against commit scores.") and drop the false "always lower" directional guarantee — or qualify it ("absent the experience and revert terms, which can subtract").

Actual Behavior

The doc asserts a strict ordering ("always lower") that the formula and the existing tests both violate whenever the negatively-signed experience term (or a revert) dominates.

Impact

A reader who trusts the "always lower" guarantee could draw the wrong conclusion when reasoning about the relationship between diff-mode and commit-mode scores (e.g., assuming a diff score upper-bounds the commit score). The surrounding docs correctly say "not comparable", so this one sentence is internally inconsistent with both the rest of the doc and the implementation. Documentation-only; no behavior change.

---

Resolution

Replaced the false "always lower" ordering claim in JitDiffReport's doc with an accurate statement that the partial and full scores are not ordered (experience is negatively signed). Commit a7e35ad.

[dekobon]

General Plan for Fix

Root Cause

The JitDiffReport doc was written assuming every term in the full
commit formula is additive and non-negative, so a partial sum of two
terms would always be a lower bound. That assumption is false: the
experience term (-0.10·ln1p(prior) - 0.05·ln1p(recent)) and the
revert purpose term (-0.20) are negatively signed, and the full
score is floored at 0. For the same size + diffusion, an experienced
author (or a revert) drives the commit score below the diff-only
partial score.

Implementation Steps

1. In src/vcs/jit.rs, edit the # Not comparable to a commit score
   section of the JitDiffReport doc. Replace the "always lower"
   sentence with a statement that the two scores are on different,
   incomparable scales and that the directional relationship is not
   guaranteed (the commit score can be higher or lower because the
   experience and revert terms subtract). The existing "rank diffs
   against other diffs, never against commit scores" sentence already
   captures the correct guidance and can stay.
2. No code change — the formula is correct; only the prose is wrong.
3. Optionally cross-check the score_diff_features doc
   (src/vcs/jit.rs:389-397) for the same "always lower" framing; it
   currently only says "not comparable", which is fine.

Tests to Add/Update

• No new behavior to test. The existing experience_lowers_the_score
  and tiny-change-by-veteran tests already prove the property that
  contradicts the old doc; optionally add a brief comment in one of
  them referencing this issue so the doc and tests stay aligned.
• cargo doc builds with RUSTDOCFLAGS="-D warnings" — confirm the
  intra-doc links in the edited section still resolve.

Verification

• cargo doc --no-deps -p big-code-analysis clean with -D warnings
• Edited doc no longer asserts a strict ordering between the two scores
• git diff touches only the JitDiffReport doc block (docs-only change)

[dekobon]

Fixed in commit a7e35ad. The JitDiffReport doc no longer claims the partial diff score is "always lower" than the full commit score. Because the experience term is negatively signed, an experienced author can push the full score below the partial; the doc now states the two are not ordered or comparable.

[dekobon]

Fixed and merged to main in #957. GitHub did not auto-close this from the batched commit's single Fixes #a #b #c … trailer (only the first referenced issue auto-closes); closing manually. See the Resolution section in the body for details.