[Wave 4] Low/info — Docs: docs/guides/human_approval_gate.md #725

Wave 4 · 6 finding(s) in 6 fix package(s). One pass over this document; keep the Turkish mirror in sync.

Findings

• DOC-D2B02-060 (docs, Low) — docs/guides/human_approval_gate.md: wrong detail — The staging directory is final_model.staging/.
  severity Low · already tracked: KNOWN-OPEN DOCS-03/DOCS-04 (S15 staging path) — docs/roadmap/phase-16-trust-surface-hardening.md:773
  Where. docs/guides/human_approval_gate.md:15; docs/reference/approve_subcommand.md:6,25; forgelm/cli/_parser.py:32,756,1249 · type: wrong detail
  The document says. The staging directory is final_model.staging/.
  What the code does. The trainer writes final_model.staging.<run_id>/.
  Code references. forgelm/trainer.py:1611
  Proposed correction. Use final_model.staging.<run_id>/.
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D2B02-062 (docs, Low) — docs/guides/human_approval_gate.md: wrong detail — The trainer fires notify_awaiting_approval 'with the run id and metrics summary'.
  severity Low
  Where. docs/guides/human_approval_gate.md:93 (Turkish mirror: docs/guides/human_approval_gate-tr.md:93) · type: wrong detail
  The document says. The trainer fires notify_awaiting_approval 'with the run id and metrics summary'.
  What the code does. The payload carries run_name, status='awaiting_approval', title, text and model_path. No metrics are sent, and the run id appears only inside the staging path. It is also sent only when webhook.notify_on_success is true.
  Code references. forgelm/webhook.py:453-487, forgelm/trainer.py:1553
  Proposed correction. "…fires notify_awaiting_approval with the run name and staging path (gated by notify_on_success)…"
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D2B02-063 (docs, Low) — docs/guides/human_approval_gate.md: wrong detail — forgelm approvals --show <run_id> (text mode) shows the request's operator, metrics and staging path.
  severity Low
  Where. docs/guides/human_approval_gate.md:110-111 (Turkish mirror: docs/guides/human_approval_gate-tr.md:110-111) · type: wrong detail
  The document says. forgelm approvals --show <run_id> (text mode) shows the request's operator, metrics and staging path.
  What the code does. Text mode prints only status, each event's timestamp/name/approver/reason/comment and the staging listing. Operator, metrics and staging_path appear only with --output-format json. Reproduced.
  Code references. forgelm/cli/subcommands/_approvals.py:415-456
  Proposed correction. Add --output-format json to the example, or change the comment to "status, event timeline and staging contents".
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D2B02-064 (docs, Low) — docs/guides/human_approval_gate.md: broken example — Example inspects outputs/run42/final_model.staging.<id>/ while approving with --output-dir ./outputs; the §5 sample uses staging_path 'outputs…
  severity Low
  Where. docs/guides/human_approval_gate.md:114 (Turkish mirror: docs/guides/human_approval_gate-tr.md:114) · type: broken example
  The document says. Example inspects outputs/run42/final_model.staging.<id>/ while approving with --output-dir ./outputs; the §5 sample uses staging_path 'outputs/run42/…'.
  What the code does. The trainer writes audit_log.jsonl and the staging dir into training.output_dir. If staging is under outputs/run42, the audit log is outputs/run42/audit_log.jsonl and approve --output-dir ./outputs finds no required event (exit 1).
  Code references. forgelm/trainer.py:345, forgelm/trainer.py:354, forgelm/trainer.py:1611, forgelm/cli/subcommands/_approve.py:520
  Proposed correction. Use one directory consistently, e.g. ls -la outputs/final_model.staging.fg-abc123def456/ and staging_path "outputs/final_model.staging.fg-abc123def456".
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D2B02-065 (docs, Low) — docs/guides/human_approval_gate.md: stale — There is no automatic gate timeout today; 'Phase 9.5 / v0.6.0+ adds the auto-fail timer' (L185: future human_approval.timeout event).
  severity Low
  Where. docs/guides/human_approval_gate.md:176 (Turkish mirror: docs/guides/human_approval_gate-tr.md:176) · type: stale
  The document says. There is no automatic gate timeout today; 'Phase 9.5 / v0.6.0+ adds the auto-fail timer' (L185: future human_approval.timeout event).
  What the code does. The package version is 0.11.1rc1 and no timer or human_approval.timeout exists in code. The 'no timeout today' part is correct.
  Code references. pyproject.toml:19
  Proposed correction. Drop the version promise: "ForgeLM does not enforce an automatic timeout; use the polling pattern below."
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

• DOC-D2B02-066 (docs, Low) — docs/guides/human_approval_gate.md: false claim — --run-id is the trainer-side flag.
  severity Low
  Where. docs/guides/human_approval_gate.md:214 (Turkish mirror: docs/guides/human_approval_gate-tr.md:214) · type: false claim
  The document says. --run-id is the trainer-side flag.
  What the code does. There is no trainer-side --run-id; the only --run-id in the parser belongs to forgelm purge.
  Code references. forgelm/cli/_parser.py:1104-1110
  Proposed correction. "--run-id exists only on forgelm purge."
  Turkish mirror. the Turkish page has the same error; fix both in the same PR

Done when

• Every finding above is fixed or closed with a reason (tick it here).
• Code fixes carry a test; doc fixes update the Turkish mirror in the same PR.

_{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.}