[Wave 4] Low/info — Docs: CLAUDE.md #717

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

Findings

• DOC-BNUM-002 (docs, Low) — CLAUDE.md: unverifiable offline — 27 single-file modules + 5 code sub-packages
  severity Low
  Where. CLAUDE.md:49; AGENTS.md:49; docs/reference/architecture.md:45 · type: unverifiable offline
  The document says. 27 single-file modules + 5 code sub-packages
  What the code does. forgelm/*.py has 29 files. That is 28 without init.py, or 27 if main.py is also excluded. The five code sub-packages (cli, data_audit, safety, verify, wizard) are correct. The CLAUDE.md tree names _pypdf_normalise, _script_sanity and _strip_pattern but omits _strict_json.py. The counting rule is not stated.
  Code references. forgelm/ top-level listing
  Proposed correction. State the counting rule, or list _strict_json.py and correct the count.

• DOC-BNUM-003 (docs, Low) — CLAUDE.md: wrong detail — config.py: Pydantic schemas (23 models)
  severity Low
  Where. CLAUDE.md:62; AGENTS.md:62 · type: wrong detail
  The document says. config.py: Pydantic schemas (23 models)
  What the code does. forgelm/config.py defines 24 BaseModel subclasses: 22 up to ForgeConfig, plus PipelineStage and PipelineConfig. ConfigError is not a model.
  Code references. forgelm/config.py:119-2099 (class list)
  Proposed correction. Change to 24, or phrase as 'about 24'.

• DOC-BNUM-004 (docs, Low) — CLAUDE.md: stale — 127 test modules / 127 test files under tests/
  severity Low
  Where. CLAUDE.md:83; AGENTS.md:83; CONTRIBUTING.md:128 · type: stale
  The document says. 127 test modules / 127 test files under tests/
  What the code does. ls tests/test_.py gives 128. README.md:165 and check_doc_numerical_claims.py report 128.
  Code references. tests/ (128 test_*.py), README.md:165
  Proposed correction. Update to 128, or drop the exact number in favour of the 'run ls tests/test_.py | wc -l' hint already present.

• DOC-D4B03-010 (docs, Low) — CLAUDE.md: stale — 'config.py # Pydantic schemas (23 models)'.
  severity Low
  Where. CLAUDE.md:62 · type: stale
  The document says. 'config.py # Pydantic schemas (23 models)'.
  What the code does. forgelm/config.py defines 24 pydantic BaseModel classes: MoeConfig, MultimodalConfig, MergeInput, MergeConfig, ModelConfig, LoraConfigModel, TrainingConfig, DistributedConfig, DataGovernanceConfig, DataConfig, BenchmarkConfig, SafetyConfig, JudgeConfig, EvaluationConfig, RiskAssessmentConfig, MonitoringConfig, ComplianceMetadataConfig, SyntheticConfig, WebhookConfig, AuthConfig, RetentionConfig,…
  Code references. forgelm/config.py:119-2099
  Proposed correction. Write '24 models' (also fix architecture.md) or drop the number.

• DOC-D4B03-011 (docs, Low) — CLAUDE.md: stale — 'tests/ # 127 test modules'.
  severity Low
  Where. CLAUDE.md:83 · type: stale
  The document says. 'tests/ # 127 test modules'.
  What the code does. 128 tests/test_*.py modules. The registry (F-196) and check_doc_numerical_claims report 128. The guard scrapes README only.
  Code references. tools/check_doc_numerical_claims.py:108-117,379
  Proposed correction. Use '128 test modules' or drop the number. Extend check_doc_numerical_claims to cover CLAUDE.md, AGENTS.md and CONTRIBUTING.md.

• DOC-D4B03-012 (docs, Low) — CLAUDE.md: stale — 'usermanuals/{en,tr}/ # 4-section user manual (training, eval, deploy, ref)'.
  severity Low
  Where. CLAUDE.md:96 · type: stale
  The document says. 'usermanuals/{en,tr}/ # 4-section user manual (training, eval, deploy, ref)'.
  What the code does. docs/usermanuals/_meta.yaml defines 9 sections: getting-started, concepts, training, data, evaluation, compliance, operations, deployment, reference. en/ and tr/ both hold these 9 directories.
  Code references. docs/usermanuals/_meta.yaml:21,64,99,156,263,314,399,490,541
  Proposed correction. Write '9-section user manual (getting-started, concepts, training, data, evaluation, compliance, operations, deployment, reference)'.

• DOC-D4B03-013 (docs, Low) — CLAUDE.md: misleading — 'no || true in CI' and 'CI || true — fake green status. Outlawed.'
  severity Low
  Where. CLAUDE.md:119, 144 · type: misleading
  The document says. 'no || true in CI' and 'CI || true — fake green status. Outlawed.'
  What the code does. Three workflow steps use || true: ci.yml:523 (bandit), nightly.yml:325 (pip-audit) and nightly.yml:333 (bandit). Each is immediately followed by a severity-gate script (check_bandit.py / check_pip_audit.py), so it is not a fake green. The rule as written is absolute, though, and the same file's gauntlet (L196) contains { bandit ... || true; }.
  Code references. .github/workflows/ci.yml:523-524, .github/workflows/nightly.yml:325,333
  Proposed correction. Reword: 'no || true that is not followed by a gate that re-checks the result (bandit/pip-audit capture JSON then run check_bandit.py / check_pip_audit.py)'.

• DOC-D4B03-014 (docs, Low) — CLAUDE.md: misleading — The notebook-pin guard 'verifies that every .ipynb in the repo pins its kernel and package versions'.
  severity Low
  Where. CLAUDE.md:269-271 · type: misleading
  The document says. The notebook-pin guard 'verifies that every .ipynb in the repo pins its kernel and package versions'.
  What the code does. check_notebook_pins.py walks notebooks/.ipynb and checks only !pip install ... forgelm==X specifiers against the pyproject version or the latest released CHANGELOG version. It does not check kernelspec, and it ignores sibling installs such as datasets.
  Code references. tools/check_notebook_pins.py:1-40
  Proposed correction. Say: 'verifies that every notebooks/.ipynb pins its forgelm install to the shipping (or latest released) version'.

• DOC-D4B03-015 (docs, Low) — CLAUDE.md: misleading — The source-path guard skips 'Markdown link hrefs (the anchor guard's job, so a broken link is reported once, never twice)'.
  severity Low
  Where. CLAUDE.md:317 · type: misleading
  The document says. The source-path guard skips 'Markdown link hrefs (the anchor guard's job, so a broken link is reported once, never twice)'.
  What the code does. check_source_path_refs.py strips hrefs only on surfaces the anchor guard covers (docs/). On every other scanned surface (CLAUDE.md, AGENTS.md, README.md, CONTRIBUTING.md, skills, site, notebooks) it validates them itself. The module docstring calls skipping them everywhere 'a hole' that was closed.
  Code references. tools/check_source_path_refs.py:57-79,236-243
  Proposed correction. Reword: '...skips fenced blocks, docs/roadmap/ and docs/design/, and strips Markdown hrefs only on docs/ (where the anchor guard owns them); hrefs elsewhere are validated here'.

• DOC-D4B03-016 (docs, Low) — CLAUDE.md: wrong detail — 'check_anchor_resolution.py defaults to --root docs'.
  severity Low
  Where. CLAUDE.md:328 · type: wrong detail
  The document says. 'check_anchor_resolution.py defaults to --root docs'.
  What the code does. The tool has no --root flag. The scanned directory is selected with --scope (default 'docs'), and --repo-root gives the repository root.
  Code references. tools/check_anchor_resolution.py:315-327
  Proposed correction. Replace with '--scope docs (its default)'.

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