docs/usermanuals/en/reference/json-output.md: false claim — Every gate exits 3; exit 3 means a gate reverted the model (reverted: true). (DOC-D3B03-005) #219

Wave 1 · theme D1-10: Documentation-only fixes · highest severity High · 1 finding(s) · effort docs fix

Summary

CI consumers who expect exit 3 on a failed gate promote models that failed their benchmark, judge or safety gate under the default configuration.

Primary finding

DOC-D3B03-005 — docs/usermanuals/en/reference/json-output.md: false claim — Every gate exits 3; exit 3 means a gate reverted the model (reverted: true).

severity High · already tracked: PARTIALLY-FIXED C33-TRAIN-JSON-CONTRACT docs/roadmap/phase-16-trust-surface-hardening.md:289-308

Where. docs/usermanuals/en/reference/json-output.md:182,193 (Turkish mirror: docs/usermanuals/tr/reference/json-output.md:182,193) · type: false claim

The document says. Every gate exits 3; exit 3 means a gate reverted the model (reverted: true).

What the code does. Gates exit 3 only under auto_revert: true, and auto_revert defaults to false. With auto_revert off, a benchmark, safety, judge or eval-loss threshold breach keeps the model: success:true, exit 0, and no error key, because the recorded reason is emitted only when success is false. I ran max_acceptable_loss 0.0001 with auto_revert:false: exit 0, success:true, no error. Separately, an unusable max_acceptable_loss with auto_revert off gives success:false, reverted:false and exit 3 (model kept), an outcome the page does not list.

Code references. forgelm/trainer.py:896-899, forgelm/trainer.py:1404-1407, forgelm/trainer.py:1461-1463, forgelm/trainer.py:1487-1489

User impact. CI consumers who expect exit 3 on a failed gate promote models that failed their benchmark, judge or safety gate under the default configuration.

Proposed correction. State the actual matrix: with auto_revert: false (the default), a failed benchmark/safety/judge/loss gate exits 0 with success: true and no error key, so check benchmark.passed / safety.passed in the envelope. Exit 3 with reverted: true happens only under auto_revert: true. Exit 3 with reverted: false is also possible (invalid loss ceiling, model kept).

Turkish mirror. the Turkish page has the same error; fix both in the same PR

Acceptance criteria

• Each statement is re-checked against the code at fix time.
• Documentation listed above is corrected in English and in its Turkish mirror in the same PR.
• Every finding in this issue is resolved or explicitly closed with a reason.

_{Found by the October 2026 ForgeLM code and documentation review against commit cab2947. Code links point at that commit; line numbers may have moved since. Finding IDs (CR-…, DOC-…, TECH-…) are stable references for this backlog.}