[Wave 3] Medium — Module sweep: Miscellaneous tooling #558

Wave 3 · 15 finding(s) in 15 fix package(s). Fix these whenever a pull request touches this module ("clean the module you touch").

Findings

• CR-MISC-007 (code, Medium) — Release matrix imports the checkout, not the packaged wheel, so the 'packaged wheel, not editable' guarantee does not hold
  severity Medium · reachability default · intent contract-violation · confidence confirmed · independently confirmed · reproduced end to end · already tracked: KNOWN-OPEN OPS-01 — docs/roadmap/phase-16-trust-surface-hardening.md:642-652
  Failure scenario. A package-data glob or packaging defect (a file in the checkout but not in the wheel) passes all 12 combos, because the tests read forgelm/templates, safety_prompts and wizard/_defaults.json from the checkout. The tag then publishes a wheel that fails for pip users. Nightly would catch only the subset its smoke script exercises.
  Where. .github/workflows/publish.yml:65, .github/workflows/publish.yml:102, tests/__init__.py:1, pyproject.toml:284-286
  Recommended fix. In the matrix, run the tests from a directory without forgelm/ (copy tests/ out) or use --import-mode=importlib plus a step asserting forgelm.file is under site-packages. Alternatively add a conftest assertion gated by an env var.

• CR-MISC-008 (code, Medium) — api_version is only MINOR-bumped although the CHANGELOG records a consumer-breaking change to the stable ForgeConfig
  severity Medium · reachability default · intent contract-violation · confidence confirmed · independently confirmed · not reproduced (code trace)
  Failure scenario. A downstream library consumer pins Version(forgelm.__api_version__) < Version('2.0') as the compatibility signal and upgrades. cfg.merge.models[0]['path'] raises TypeError at runtime without any API-version signal.
  Where. CHANGELOG.md:86-90, forgelm/_version.py:48-66, docs/standards/release.md:27-33, tests/_data/api_signatures_1.2.0.json:1
  Recommended fix. Either bump api_version MAJOR with a Breaking entry, or record in release.md an explicit decision that nested config-schema shape is outside the stable signature contract. Extend the snapshot to cover nested model fields.

• CR-MISC-009 (code, Medium) — SBOM is a workflow artifact but the audit cookbook sends the reader to the GitHub release page
  severity Medium · reachability default · intent contract-violation · confidence confirmed · independently confirmed · not reproduced (code trace) · already tracked: KNOWN-OPEN OPS-02..19 (S12) — docs/roadmap/phase-16-trust-surface-hardening.md:667-668
  Failure scenario. The auditor's command returns no assets; supply-chain evidence expires with the artifact retention window.
  Where. docs/guides/iso_soc2_deployer_guide.md:202, .github/workflows/publish.yml:106, .github/workflows/publish.yml:106-111, .github/workflows/publish.yml:104
  Recommended fix. Attach the SBOMs to the GitHub release or correct the guide.

• CR-MISC-010 (code, Medium) — QMS data-management SOP still treats quality filter as optional
  severity Medium · reachability default · intent contract-violation · confidence confirmed · independently confirmed · reproduced end to end
  Failure scenario. An operator following the SOP checklist may skip reviewing quality_summary, believing it only exists when the flag was passed.
  Where. docs/qms/sop_data_management.md:84, docs/qms/sop_data_management.md:106, docs/qms/sop_data_management-tr.md:85, docs/qms/sop_data_management-tr.md:106
  Recommended fix. Update the SOP text in both languages.

• CR-MISC-012 (code, Medium) — Leakage manual page says the audit 'refuses to certify a leaky split' but the audit exits 0 and gates nothing on leakage
  severity Medium · reachability default · intent contract-violation · confidence confirmed · independently confirmed · reproduced end to end
  Failure scenario. A reader of the page's opening relies on forgelm audit failing CI on a leaky split. A corpus with 95% leakage passes the CI step with exit 0, as the page's own example shows.
  Where. docs/usermanuals/en/data/leakage.md:10, docs/usermanuals/en/data/leakage.md:44, docs/usermanuals/tr/data/leakage.md:10
  Recommended fix. Reword line 10 (EN and TR) to say the check reports leakage and does not gate it.

• CR-MISC-013 (code, Medium) — Docs say malformed input on verify-* exits 1, but verify-audit exits 6 on an undecodable line
  severity Medium · reachability default · intent contract-violation · confidence confirmed · independently confirmed · reproduced end to end · already tracked: KNOWN-OPEN C31-EXIT-CODE-PROSE — docs/roadmap/phase-16-trust-surface-hardening.md:782-784
  Failure scenario. A reader of usage.md expects 1 for a malformed log and wires retry logic on it.
  Where. docs/reference/usage.md:270, docs/guides/troubleshooting.md:396, docs/reference/verify_audit.md:35, docs/guides/troubleshooting-tr.md:418
  Recommended fix. Qualify the general row: 'malformed input exits 1, except verify-audit, where a malformed log line is treated as tampering (6)'.

• CR-MISC-014 (code, Medium) — Release docs and a test docstring describe gates publish.yml does not have
  severity Medium · reachability default · intent contract-violation · confidence confirmed · independently confirmed · reproduced end to end · already tracked: KNOWN-OPEN OPS-02..19 (S12) — docs/roadmap/phase-16-trust-surface-hardening.md:657-659,670-671
  Failure scenario. A reader of testing.md or test_guard_wiring.py believes a release tag is vulnerability-gated, but it is not.
  Where. docs/standards/testing.md:141, tests/test_guard_wiring.py:79-84, docs/standards/release.md:277-278, docs/standards/release.md:259
  Recommended fix. Align testing.md:140-141, the test_guard_wiring.py _NIGHTLY_ONLY justification, and release.md:243/259/277 with publish.yml (or add the gate it promises).

• CR-MISC-015 (code, Medium) — User manual gives exit 1 for an unwritable --audit-dir; code and guide exit 2
  severity Medium · reachability default · intent contract-violation · confidence confirmed · independently confirmed · reproduced end to end
  Failure scenario. A CI script written from the user manual branches on exit 1 for this case and misclassifies the real exit 2.
  Where. docs/usermanuals/en/compliance/gdpr-erasure.md:97, docs/usermanuals/tr/compliance/gdpr-erasure.md:101, forgelm/cli/subcommands/_reverse_pii.py:575, forgelm/cli/subcommands/_reverse_pii.py:704
  Recommended fix. Move 'unwritable --audit-dir' to the exit-2 row in both language mirrors.

• CR-MISC-016 (code, Medium) — GPU-cost user manual describes detection and records that do not exist
  severity Medium · reachability default · intent contract-violation · confidence confirmed · independently confirmed · reproduced end to end
  Failure scenario. An operator follows the manual. They grep the audit log for run_complete and find nothing, or drop in gpu_profiles.local.yaml and it has no effect.
  Where. docs/usermanuals/en/operations/gpu-cost.md:8-14, docs/usermanuals/en/operations/gpu-cost.md:27-34, docs/usermanuals/en/operations/gpu-cost.md:55-67, docs/usermanuals/en/operations/gpu-cost.md:135
  Recommended fix. Rewrite the page around the real resource_usage block (JSON envelope, compliance_report.json, webhook metrics) and remove the claims about nvidia-smi, run_complete, gpu_profiles and the profile list.

• CR-MISC-017 (code, Medium) — verify_annex_iv_subcommand reference (EN+TR) omits the Tier-3 audit corroboration and says an absent-hash pipeline manifest exits 0
  severity Medium · reachability default · intent contract-violation · confidence confirmed · independently confirmed · reproduced end to end · already tracked: KNOWN-OPEN TRUST-05 — docs/roadmap/phase-16-trust-surface-hardening.md:438-441
  Failure scenario. Real pipeline run with metadata.manifest_hash removed, verified without FORGELM_AUDIT_SECRET: prints 'FAIL ... unattested (no_audit_secret)' and exits 1. The reference page says 'OK (UNVERIFIED)' with exit 0.
  Where. docs/reference/verify_annex_iv_subcommand.md:81-85, docs/reference/verify_annex_iv_subcommand.md:79-85, docs/reference/verify_annex_iv_subcommand.md:143-153 (table lists stages_total, status_census and stage_dispositions; only audit_corroboration is missing), docs/reference/verify_annex_iv_subcommand.md:140-155
  Recommended fix. Add a Tier-3 section to the reference page (EN and TR) that mirrors usermanuals/en/compliance/annex-iv.md:157-174. Make the absent-hash row conditional on a corroborated audit log, update the example and the envelope table to the 12-key shape, and revise the 'no keyed equivalent' and residual-gap text.

• CR-MISC-018 (code, Medium) — Performance docs present 'ingestion.strategy' as a config knob and list 'semantic' as a CLI --strategy choice
  severity Medium · reachability default · intent contract-violation · confidence confirmed · independently confirmed · reproduced end to end
  Failure scenario. An operator follows the knob heading and adds ingestion: {strategy: paragraph} to the YAML: load_config raises ConfigError 'ingestion Extra inputs are not permitted'. An operator who picks 'semantic' from the guide comment gets argparse exit 2.
  Where. docs/usermanuals/en/reference/performance.md:28, docs/usermanuals/tr/reference/performance.md:28, docs/guides/performance.md:117-121, docs/guides/performance.md:191
  Recommended fix. Retitle the section to forgelm ingest --strategy (EN and TR). Drop 'semantic' from the guide's choice comment, fix the :191 cross-reference, and put the inline comments on their own lines.

• CR-MISC-019 (code, Medium) — config_snapshot.yaml is documented as written by every run but no code writes it
  severity Medium · reachability default · intent contract-violation · confidence confirmed · independently confirmed · reproduced end to end
  Failure scenario. An auditor asks for the exact training config of a run; the documented config_snapshot.yaml does not exist, and only an irreversible sha256 config_hash is present.
  Where. docs/usermanuals/en/getting-started/first-run.md:172, docs/usermanuals/en/getting-started/project-layout.md:27, docs/usermanuals/en/training/sft.md:132, docs/usermanuals/tr/getting-started/first-run.md:172
  Recommended fix. Write the validated config (secrets redacted) to <output_dir>/config_snapshot.yaml, or drop the row from all six docs.

• CR-MISC-020 (code, Medium) — DPO guide recommends reference_free: true, which the config schema rejects
  severity Medium · reachability default · intent contract-violation · confidence confirmed · independently confirmed · reproduced end to end
  Failure scenario. An operator follows the memory advice, adds reference_free: true, and the config fails validation (exit 1).
  Where. docs/usermanuals/en/training/dpo.md:114, docs/usermanuals/tr/training/dpo.md:105
  Recommended fix. Remove the bullet from dpo.md and its TR mirror.

• CR-MISC-021 (code, Medium) — Privacy policy invites GDPR access/erasure requests via public GitHub Issues
  severity Medium · reachability default · intent intended-but-harmful · confidence confirmed · independently confirmed · reproduced end to end · already tracked: KNOWN-OPEN DOCS-02/14/15/16 (S15 privacy) — docs/roadmap/phase-16-trust-surface-hardening.md:772
  Where. site/js/translations.js:4390, site/js/translations.js:4354, docs/standards/release.md:366
  Recommended fix. Point data-subject requests only to the private contact form (or a dedicated address). Add a SECURITY.md that names the private disclosure channel and the 72 h acknowledgement target.

• CR-MISC-022 (code, Medium) — User manual tells users to set seed: in YAML; the schema rejects it with exit 1
  severity Medium · reachability default · intent contract-violation · confidence confirmed · independently confirmed · reproduced end to end · already tracked: KNOWN-OPEN C31-DOC-SCHEMA-PROSE — docs/roadmap/phase-16-trust-surface-hardening.md:785-786
  Failure scenario. A user follows the manual, adds 'seed: 42', and the run fails at config validation with exit 1.
  Where. docs/usermanuals/en/deployment/chat.md:125, docs/usermanuals/tr/deployment/chat.md:126
  Recommended fix. Remove the advice, or implement the seed field (see the previous finding). check_usermanual_schema_drift does not catch this because it checks fenced YAML only, not inline prose.

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