refactor(vcs)!: rename "vcs jit" to "vcs commit" and --fail-over to --fail-above #603

Current behavior

The commit-level risk scorer is spelled bca vcs jit (big-code-analysis-cli/src/lib.rs:492), and its gate flag is --fail-over <SCORE> (lib.rs:536-541).

• "JIT" is defect-prediction-literature jargon ("just-in-time defect prediction"); every piece of help/doc text must immediately translate it ("just-in-time (commit-level)") because no user outside that literature can guess it — and most readers will parse "JIT" as just-in-time compilation.
• --fail-over reads as HA failover; what it means is "fail the gate when the score is at or above N".

Why it's a problem

Both names require translation at every point of contact. Discoverability suffers: a user scanning bca vcs --help for "score this commit" has no reason to try jit, and --fail-over 0.8 is opaque (or actively misleading) in a CI config that teammates read.

Note: medium confidence. The literature naming is defensible — "JIT" is the established term in the defect-prediction research this feature implements, and renaming costs the connection to that literature. This is a pure-UX argument; treat this issue as a proposal for discussion rather than a settled decision.

Proposed 2.0 design

1. Rename the subcommand to bca vcs commit [<rev>], keeping jit as a hidden alias for one release cycle.
2. Rename --fail-over to --fail-above <SCORE> (or --max-score), with the old name as a hidden alias for one cycle.
3. Keep "just-in-time (JIT)" in the long help / book as the literature cross-reference.

Breaking?

Yes — canonical names change; aliases soften it for one cycle.

Part of the 2.0 UX audit; rolls up to the 2.x breaking-change roadmap #505.

Resolution Plan

Decision settled (design audit, 2026-06-10)

The issue's "medium confidence — discuss first" caveat is now resolved. Decided:

• Subcommand: bca vcs jit → bca vcs commit (takes the optional [<rev>]).
  Keep "just-in-time (JIT)" in the long help and book as the literature
  cross-reference, so the research tie is preserved in prose without making
  users guess jit as a command.
• Flag: --fail-over <SCORE> → --fail-above <SCORE> — directly states
  "fail the gate when the score is at or above N".
• Transition: hidden one-cycle aliases. jit and --fail-over keep
  working but are hidden from help for one release, then removed — matching the
  refactor(cli)!: naming sweep — --warning, --num-jobs, and the unnamed default output format #604 precedent (num-jobs, warning). Coordinate the
  deprecated-alias-in-use warning with refactor(cli): unify one-cycle deprecation mechanisms and warn on deprecated alias use #646 (one-cycle deprecation unification)
  so the warning is emitted through the shared mechanism, not a bespoke one.

Steps

1. Rename the subcommand enum variant / clap name to commit with a hidden
   alias = "jit" (big-code-analysis-cli/src/lib.rs:492); rename the
   fail_over field / flag to fail_above with a hidden alias = "fail-over"
   (lib.rs:536-541).
2. Sweep user-facing strings: help text, the gate output prefix
   (vcs jit: score … → vcs commit: score …), the book pages from feat(vcs): change-history (VCS) metrics with a git backend (#328) #574, and
   man pages via cargo xtask.
3. Emit a deprecation warning when the jit / --fail-over aliases are used,
   routed through refactor(cli): unify one-cycle deprecation mechanisms and warn on deprecated alias use #646's unified mechanism (or, if refactor(cli): unify one-cycle deprecation mechanisms and warn on deprecated alias use #646 has not landed, a local
   warning consistent with the refactor(cli)!: naming sweep — --warning, --num-jobs, and the unnamed default output format #604 alias pattern — note the dependency).
4. Regression tests: both spellings parse for one cycle; the aliases are hidden
   from --help (snapshot the updated help); gate exit codes unchanged
   (2 on breach per the exit-code contract); --fail-above and --fail-over
   produce identical behavior.
5. Regenerate man pages and review the man/ diff (drift gate).
6. CHANGELOG ## [Unreleased]: (breaking) entry, deferred to 2.0; list both
   renames and the one-cycle alias horizon.
7. make pre-commit.

Dependency

• Soft dependency on refactor(cli): unify one-cycle deprecation mechanisms and warn on deprecated alias use #646 for the shared deprecation-warning mechanism; can
  land independently with a local warning if refactor(cli): unify one-cycle deprecation mechanisms and warn on deprecated alias use #646 is not yet merged.

Assessment