cicd.md 'JSON output mode' section documents a non-existent .verdict key and JSON log events on stdout (CR-A04-008)

Wave 1 · theme D1-8: Docs describing features that do not exist (doc side of code findings) · highest severity High · 1 finding(s) · effort trivial

Summary

A log aggregator built on cicd.md:153 receives no events, and a script testing .verdict == "success" never matches.

Primary finding

CR-A04-008 — cicd.md 'JSON output mode' section documents a non-existent .verdict key and JSON log events on stdout

severity High · reachability default · intent contract-violation · confidence confirmed · independently confirmed · reproduced end to end

What happens. cicd.md:149-150 shows forgelm --config ... --output-format json | jq '.verdict' printing "success", but the training envelope has no 'verdict' key (forgelm/cli/_result.py:11-20), so jq prints null (after the stdout pollution above). cicd.md:153 says every event logged to stderr is also emitted as a JSON object on stdout. In fact _setup_logging in JSON mode only raises the level to WARNING (forgelm/cli/_logging.py:25-33) and logs remain plain text on stderr.

Where.

Evidence.

Training envelope keys observed: success, metrics, final_model_path, reverted, awaiting_approval, run_id, config_hash, resource_usage, estimated_cost_usd (ot2.log / clean.out).

Recommended fix. Replace with jq '.success' and remove the stdout event-stream claim (EN+TR).

Acceptance criteria

A regression test reproduces the failure scenario and asserts the corrected behaviour.
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.}

Where to start

Thanks for taking a look. Claim it by starting a comment with /assign so nobody duplicates the work.

This section has two errors, and #216 reports the first of them on the same lines. One pull request fixes both issues; put Fixes #433 and Fixes #216 in its description.

Files. The "JSON output mode" section of docs/usermanuals/en/operations/cicd.md (about lines 146-153) and of its Turkish mirror docs/usermanuals/tr/operations/cicd.md (about lines 147-154).

What is wrong.

The example pipes the training run into jq '.verdict' and shows "success". The training result has no verdict key, so jq prints null; the key is success. The envelope is built by _build_result_json_envelope in forgelm/cli/_result.py.
The sentence under it says every event logged to stderr is also emitted as a JSON object on stdout. That is not true. In JSON mode, _setup_logging in forgelm/cli/_logging.py only raises the log level to WARNING; logs stay plain text on stderr and stdout carries only the envelope.

What to change (already decided).

In both languages, change the example to the block below. The block is identical in English and Turkish:
```
$ forgelm --config configs/run.yaml --output-format json | jq '.success'
true
```
EN: replace the sentence under the block with: The JSON envelope goes to stdout; human-readable logs go to stderr. See [JSON output schemas](#/reference/json-output) for every field.
TR: replace the matching sentence with: JSON envelope **stdout**'a gider; insana okunabilir loglar **stderr**'e gider. Tüm alanlar için [JSON çıktı şemaları](#/reference/json-output) sayfasına bakın. The first half is copied from the Turkish JSON-output page, so you do not need to write Turkish; a maintainer reads it in review.
Leave the three forgelm audit ... | jq -e '.verdict != "errors" ...' lines higher up on the page alone. They belong to TR mirror drift in docs/usermanuals/en/operations/cicd.md: GitLab audit job: forgelm audit data/train.jsonl --output-format json | jq -e '.verdict != "errors" and .pii_summary.severity != "high"' (… (DOC-TR15-001) #357.

Note for the PR description. #412 tracks real training runs that print some library text to stdout before the envelope. This PR corrects only the documented key and the logging sentence; it changes no code.

Test. Add a test to tests/test_usermanual_reference_consistency.py and parametrize it over lang in ("en", "tr").

Read docs/usermanuals/<lang>/operations/cicd.md and find the --output-format json | jq '<filter>' line of the training run.
Assert that the filter's key is one of the keys of _build_result_json_envelope(TrainResult(success=True)). forgelm.cli._result and forgelm.results provide them; tests/test_strict_json.py imports both.
Assert that the retired sentence is gone: in English also emitted as a JSON object on stdout, in Turkish stdout'ta da JSON nesnesi olarak çıkar.

The test fails today and passes after the fix.

pytest tests/test_usermanual_reference_consistency.py --no-cov
python3 tools/check_bilingual_parity.py --strict
python3 tools/check_bilingual_code_blocks.py --strict
python3 tools/check_anchor_resolution.py --strict
python3 tools/check_tr_links_prefer_mirror.py --strict
python3 tools/check_usermanual_self_contained.py --strict

Add one line under ## [Unreleased] → ### Fixed in CHANGELOG.md.

Open the PR against development with Fixes #433 and Fixes #216 (findings CR-A04-008 and DOC-D3B02-016).

/assign

@Mr-Neutr0n

Assigned to @Mr-Neutr0n. Thank you! Please open the pull request against development and link it with Fixes #433 (or Refs #433 if it resolves only part of a grouped issue); see Working on an issue. If you cannot continue, comment /unassign so someone else can take it.

docs: complete CI/CD JSON output review fixes

fix: preserve CI exit provenance and guide section routes

test: cover zero-exit failures and native guide clicks

Navigation Menu

Repository navigation

cicd.md 'JSON output mode' section documents a non-existent .verdict key and JSON log events on stdout (CR-A04-008) #433

Summary

Primary finding

CR-A04-008 — cicd.md 'JSON output mode' section documents a non-existent .verdict key and JSON log events on stdout

Acceptance criteria

Where to start

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

cicd.md 'JSON output mode' section documents a non-existent .verdict key and JSON log events on stdout (CR-A04-008) #433

Description

Summary

Primary finding

CR-A04-008 — cicd.md 'JSON output mode' section documents a non-existent .verdict key and JSON log events on stdout

Acceptance criteria

Activity

cemililik commented on Oct 22, 2026

Where to start

Mr-Neutr0n commented on Nov 2, 2026

github-actions commented on Nov 2, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions