[Wave 4] Low/info — Docs: repository root files (part 2/2) #796

Wave 4 · 14 finding(s) in 14 fix package(s). Documents with fewer than five findings each in this wave, grouped by directory.

Findings

• DOC-D4B04-010 (docs, Low) — .claude/skills/add-config-field/SKILL.md: stale — List of config classes to choose from
  severity Low
  Where. .claude/skills/add-config-field/SKILL.md:31-39 · type: stale
  The document says. List of config classes to choose from
  What the code does. forgelm/config.py also defines DistributedConfig (:750), SyntheticConfig (:1324), MergeConfig (:177), MultimodalConfig (:128), MoeConfig (:119), PipelineConfig (:2099) and PipelineStage (:2002); ForgeConfig has distributed/merge/synthetic/pipeline blocks (config.py:1604+). A field for those areas would be told 'none fit'.
  Code references. forgelm/config.py:119-177, forgelm/config.py:750, forgelm/config.py:1324, forgelm/config.py:2099
  Proposed correction. Add the missing classes to the list.

• DOC-D4B04-011 (docs, Low) — .claude/skills/add-config-field/SKILL.md: wrong detail — If none fit, a new config class may be needed: see architecture.md section 1
  severity Low
  Where. .claude/skills/add-config-field/SKILL.md:41 · type: wrong detail
  The document says. If none fit, a new config class may be needed: see architecture.md section 1
  What the code does. docs/standards/architecture.md:150 section 1 is the 'each module owns one concern' table; it has nothing on adding config classes (config flow is section 2, :178).
  Code references. docs/standards/architecture.md:150-178
  Proposed correction. Cite architecture.md section 2 'Config is the one-way contract', or drop the pointer.

• DOC-D4B04-012 (docs, Low) — .claude/skills/add-config-field/SKILL.md: wrong detail — the guard reads description= off the FieldInfo
  severity Low
  Where. .claude/skills/add-config-field/SKILL.md:61-62 · type: wrong detail
  The document says. the guard reads description= off the FieldInfo
  What the code does. tools/check_field_descriptions.py:1-18 is AST-based and deliberately does not import forgelm.config; it inspects Field(...) call keywords. The rule itself (bare field with docstring fails) is true (reproduced: exit 1).
  Code references. tools/check_field_descriptions.py:1-18
  Proposed correction. Say: the guard walks forgelm/config.py with the AST and requires a description= keyword on each Field(...).

• DOC-D4B04-013 (docs, Low) — .claude/skills/add-test/SKILL.md: stale — tests/conftest.py is 'the minimal_config factory'; template does from tests.conftest import minimal_config
  severity Low
  Where. .claude/skills/add-test/SKILL.md:23,48 · type: stale
  The document says. tests/conftest.py is 'the minimal_config factory'; template does from tests.conftest import minimal_config
  What the code does. The factory is defined in tests/_helpers/factories.py:23. conftest.py:9-15 re-exports it only for legacy imports and says new tests should use the minimal_config pytest fixture (conftest.py:18-30). Also, minimal_config overrides replace whole top-level sections (factories.py doc).
  Code references. tests/_helpers/factories.py:23, tests/conftest.py:9-30
  Proposed correction. Point to tests/_helpers/factories.py and show the minimal_config fixture argument (def test_x(minimal_config)) as the preferred form; note that top-level overrides replace the whole section.

• DOC-D4B04-014 (docs, Low) — .claude/skills/add-test/SKILL.md: misleading — Never mock: internal forgelm.* modules
  severity Low
  Where. .claude/skills/add-test/SKILL.md:95-99 · type: misleading
  The document says. Never mock: internal forgelm.* modules
  What the code does. docs/standards/testing.md:161 restricts this to forgelm internals that have a fast real implementation. The skill's own examples (and the in-repo tests) patch forgelm seams (forgelm.webhook.safe_post, forgelm.safety._orchestrator._load_safety_classifier).
  Code references. docs/standards/testing.md:161
  Proposed correction. Write: 'Never mock forgelm-internal code that has a fast real implementation; patch heavyweight seams (loaders, chokepoints) at the name the caller resolves.'

• DOC-D4B04-015 (docs, Low) — .claude/skills/add-test/SKILL.md: broken example — Example calls model.load(cfg) returning result.device
  severity Low
  Where. .claude/skills/add-test/SKILL.md:105-108 · type: broken example
  The document says. Example calls model.load(cfg) returning result.device
  What the code does. No forgelm.model.load exists; the loader is get_model_and_tokenizer (forgelm/init.py:150 tier map). Illustrative pseudo-code but presented as a real pattern.
  Code references. forgelm/__init__.py:150
  Proposed correction. Use forgelm.model.get_model_and_tokenizer or mark the snippet as pseudo-code.

• DOC-D4B04-016 (docs, Low) — .claude/skills/add-test/SKILL.md: wrong detail — tests/test_safety.py stubs the module with _recording_pipeline()
  severity Low
  Where. .claude/skills/add-test/SKILL.md:134-138 · type: wrong detail
  The document says. tests/test_safety.py stubs the module with _recording_pipeline()
  What the code does. No _recording_pipeline exists. The helper is _fake_pipeline(self, captured) at tests/test_safety.py:247-256; the patch.dict('sys.modules') pattern itself is accurate (test_safety.py:259-262).
  Code references. tests/test_safety.py:247-262
  Proposed correction. Name _fake_pipeline(captured) (tests/test_safety.py) instead of _recording_pipeline().

• DOC-D4B04-017 (docs, Low) — .claude/skills/add-trainer-feature/SKILL.md: misleading — Example config adds ipo_beta: float = 0.1 as a bare annotation
  severity Low
  Where. .claude/skills/add-trainer-feature/SKILL.md:76-79 · type: misleading
  The document says. Example config adds ipo_beta: float = 0.1 as a bare annotation
  What the code does. Contradicts the sibling add-config-field rule: a bare name: T = default fails tools/check_field_descriptions.py --strict (reproduced, exit 1). Real analogue: dpo_beta = Field(default=0.1, gt=0, description=...) at forgelm/config.py:506. The trainer_type Literal order in the example also differs from config.py:464 (sft, orpo, dpo, simpo, kto, grpo).
  Code references. forgelm/config.py:464, forgelm/config.py:506
  Proposed correction. Write ipo_beta: float = Field(default=0.1, gt=0, description=...).

• DOC-D4B04-018 (docs, Low) — .claude/skills/cut-release/SKILL.md: misleading — stable-tier library symbol (anything in forgelm.all)
  severity Low
  Where. .claude/skills/cut-release/SKILL.md:105-108 · type: misleading
  The document says. stable-tier library symbol (anything in forgelm.all)
  What the code does. forgelm/init.py:142-177 (_STABILITY_TIERS) puts experimental symbols (prepare_dataset, get_model_and_tokenizer, WebhookNotifier, run_benchmark, SyntheticDataGenerator ...) in all as well; _version.py states only stable symbols are covered by the bump rule. The opening paragraph (L43) 'adds a new lazy-import target bumps both' has the same overreach.
  Code references. forgelm/__init__.py:142-177, forgelm/_version.py:47-53
  Proposed correction. Say 'a stable-tier symbol (see forgelm._STABILITY_TIERS; experimental symbols in all do not trigger the rule)'.

• DOC-D4B04-019 (docs, Low) — .claude/skills/cut-release/SKILL.md: misleading — Local verification: 'All four must pass' (ruff/pytest/cov/dry-run) before tagging
  severity Low
  Where. .claude/skills/cut-release/SKILL.md:145-161 · type: misleading
  The document says. Local verification: 'All four must pass' (ruff/pytest/cov/dry-run) before tagging
  What the code does. The block lists more than four commands (ruff check + format, pytest, pytest --cov, dry-run, install, --version) and is the shortened gauntlet that CLAUDE.md says must not stand in for the full chain (the 'All 31 must pass' list incl. check_release_record_sync, update_site_version --check, which CI runs: ci.yml:423, :481).
  Code references. .github/workflows/ci.yml:423, .github/workflows/ci.yml:481
  Proposed correction. State that the full CLAUDE.md gauntlet (esp. check_release_record_sync.py --strict and update_site_version.py --check) is the pre-tag gate and fix the count wording.

• DOC-D4B04-020 (docs, Low) — .claude/skills/review-pr/SKILL.md: misleading — No print() outside the forgelm/cli/ package's output blocks
  severity Low
  Where. .claude/skills/review-pr/SKILL.md:61 · type: misleading
  The document says. No print() outside the forgelm/cli/ package's output blocks
  What the code does. docs/standards/logging-observability.md:31,235 also sanction print() in forgelm/chat.py and forgelm/wizard/ (interactive UIs).
  Code references. docs/standards/logging-observability.md:31
  Proposed correction. Add the chat.py and wizard/ carve-outs.

• DOC-D4B04-021 (docs, Low) — .claude/skills/sync-bilingual-docs/SKILL.md: stale — docs/README.md (if bilingual)
  severity Low · already tracked: KNOWN-OPEN DOCS-17|DOCS-13 docs/roadmap/phase-16-trust-surface-hardening.md:817-819
  Where. .claude/skills/sync-bilingual-docs/SKILL.md:22 · type: stale
  The document says. docs/README.md (if bilingual)
  What the code does. docs/README.md does not exist in the snapshot (docs/ top level: product_strategy(-tr).md, roadmap(-tr).md only).
  Code references. docs/
  Proposed correction. Remove the line.

• DOC-D4B04-022 (docs, Low) — .claude/skills/sync-bilingual-docs/SKILL.md: stale — static-site SPA viewer site/usermanual.html
  severity Low
  Where. .claude/skills/sync-bilingual-docs/SKILL.md:40 · type: stale
  The document says. static-site SPA viewer site/usermanual.html
  What the code does. site/usermanual.html does not exist; the viewer is site/guide.html with site/js/guide.js.
  Code references. site/guide.html, site/js/guide.js
  Proposed correction. Use site/guide.html.

• DOC-D4B04-023 (docs, Low) — .claude/skills/sync-bilingual-docs/SKILL.md: misleading — Rules/verification require only 'same H2 count, same order'
  severity Low
  Where. .claude/skills/sync-bilingual-docs/SKILL.md:64-65,117-120 · type: misleading
  The document says. Rules/verification require only 'same H2 count, same order'
  What the code does. The guards pin H2/H3/H4 spine (check_bilingual_parity.py), fenced-block count, language tag and top-level YAML keys per block (check_bilingual_code_blocks.py:1-30, :148-153). The skill's own table (L10-15) says so; the rules section and grep check are weaker.
  Code references. tools/check_bilingual_code_blocks.py:148-153
  Proposed correction. State same H2/H3/H4 spine and identical code blocks; point to the strict guards.

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