[Wave 3] Medium — Docs: docs/design/iso27001_soc2_alignment.md #575

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

Findings

• DOC-D2B03-013 (docs, Medium) — docs/design/iso27001_soc2_alignment.md: wrong detail — Genesis manifest sidecar at <output_dir>/audit_log.manifest.json.
  severity Medium
  Where. docs/design/iso27001_soc2_alignment.md:107 · type: wrong detail
  The document says. Genesis manifest sidecar at <output_dir>/audit_log.manifest.json.
  What the code does. The sidecar is <output_dir>/audit_log.jsonl.manifest.json (log path + '.manifest.json').
  Code references. forgelm/compliance.py:175-176, forgelm/compliance.py:2456
  Proposed correction. <output_dir>/audit_log.jsonl.manifest.json

• DOC-D2B03-014 (docs, Medium) — docs/design/iso27001_soc2_alignment.md: wrong detail — forgelm doctor checks 'HF auth'; 'reports VRAM / CPU / RAM'; 'reports installed packages + versions'; 'pyproject.toml pins'; 'resource report'…
  severity Medium
  Where. docs/design/iso27001_soc2_alignment.md:114,232,237,250,332 · type: wrong detail
  The document says. forgelm doctor checks 'HF auth'; 'reports VRAM / CPU / RAM'; 'reports installed packages + versions'; 'pyproject.toml pins'; 'resource report' (A1.1).
  What the code does. The doctor probes are forgelm install, Python, torch/CUDA, numpy/torch ABI, GPU inventory (VRAM only), optional-extra presence, Hub reachability (an unauthenticated HEAD) or the offline cache, workspace disk space, FORGELM_OPERATOR and the pypdf profile. There is no authentication check, no CPU/RAM report and no package listing. pyproject declares version ranges, not pins.
  Code references. forgelm/cli/subcommands/_doctor.py:143-930, forgelm/cli/subcommands/_doctor.py:359-416, forgelm/cli/subcommands/_doctor.py:464-470, pyproject.toml:45-67
  Proposed correction. "forgelm doctor — Python / torch+CUDA / GPU VRAM inventory / optional extras present / HF Hub reachability (or offline cache) / disk / FORGELM_OPERATOR"; for A.8.19 say "pip install forgelm==X.Y.Z (pyproject declares version ranges)".

• DOC-D2B03-016 (docs, Medium) — docs/design/iso27001_soc2_alignment.md: wrong detail — A.5.12: 'compliance.risk_classification 5-tier (unacceptable/high-risk/limited-risk/minimal-risk/out-of-scope)'.
  severity Medium
  Where. docs/design/iso27001_soc2_alignment.md:164 · type: wrong detail
  The document says. A.5.12: 'compliance.risk_classification 5-tier (unacceptable/high-risk/limited-risk/minimal-risk/out-of-scope)'.
  What the code does. The allowed values are unknown, minimal-risk, limited-risk, high-risk and unacceptable. 'out-of-scope' fails validation (reproduced).
  Code references. forgelm/config.py:1238
  Proposed correction. "5-tier (unacceptable / high-risk / limited-risk / minimal-risk / unknown)".

• DOC-D2B03-017 (docs, Medium) — docs/design/iso27001_soc2_alignment.md: wrong detail — A.5.13 / PI1.3: 'model_card.md produced per run'.
  severity Medium
  Where. docs/design/iso27001_soc2_alignment.md:165,342 · type: wrong detail
  The document says. A.5.13 / PI1.3: 'model_card.md produced per run'.
  What the code does. The model card is written as README.md inside the final model directory, with HF YAML front-matter.
  Code references. forgelm/model_card.py:342
  Proposed correction. "model card (final_model/README.md, HF YAML front-matter)"

• DOC-D2B03-021 (docs, Medium) — docs/design/iso27001_soc2_alignment.md: false claim — A.6.8: 'forgelm webhook notifies external systems'.
  severity Medium
  Where. docs/design/iso27001_soc2_alignment.md:202 · type: false claim
  The document says. A.6.8: 'forgelm webhook notifies external systems'.
  What the code does. There is no forgelm webhook subcommand; the CLI rejects it with exit 2. Webhooks are configured through the webhook: config block and fire from training, approve/reject and pipeline runs.
  Code references. forgelm/config.py:1461-1500, forgelm/webhook.py:429-661
  Proposed correction. "the webhook: config block notifies external systems of lifecycle events".

• DOC-D2B03-022 (docs, Medium) — docs/design/iso27001_soc2_alignment.md: false claim — PI1.5: 'Annex IV bundle co-locates manifest + report + audit + integrity in one ZIP'.
  severity Medium
  Where. docs/design/iso27001_soc2_alignment.md:344 · type: false claim
  The document says. PI1.5: 'Annex IV bundle co-locates manifest + report + audit + integrity in one ZIP'.
  What the code does. export_evidence_bundle exists as a library function but no CLI path calls it. It zips only the directory it is given. The audit log sits at the output_dir root and model_integrity.json in final_model/, both outside compliance/.
  Code references. forgelm/compliance.py:2299-2330, forgelm/trainer.py:2087-2088, forgelm/trainer.py:2163, forgelm/trainer.py:354
  Proposed correction. "compliance/ bundle (compliance_report.json, training_manifest.yaml, data_provenance.json, annex_iv_metadata.json, data_governance_report.json); package it together with audit_log.jsonl (+ manifest) and final_model/model_integrity.json yourself, or via the library export_evidence_bundle(dir, zip_path)".

• DOC-D2B03-023 (docs, Medium) — docs/design/iso27001_soc2_alignment.md: stale — P4.1: 'legacy alias evaluation.staging_ttl_days forwards transparently during the v0.5.5 → v0.6.x deprecation window'.
  severity Medium
  Where. docs/design/iso27001_soc2_alignment.md:361 · type: stale
  The document says. P4.1: 'legacy alias evaluation.staging_ttl_days forwards transparently during the v0.5.5 → v0.6.x deprecation window'.
  What the code does. The alias was removed in v0.8.0. evaluation.staging_ttl_days is now rejected (extra_forbidden, dry-run exit 1; reproduced).
  Code references. forgelm/config.py:1224-1226, forgelm/config.py:1559-1565
  Proposed correction. "retention.staging_ttl_days (the legacy evaluation.staging_ttl_days alias was removed in v0.8.0) + forgelm purge --check-policy".

• DOC-D2B03-024 (docs, Medium) — docs/design/iso27001_soc2_alignment.md: stale — §5 'what ForgeLM does NOT yet ship': 'SBOM exists; supply-chain CVE scanning does not'; '[tool.bandit] ... no workflow consumes it yet'.
  severity Medium
  Where. docs/design/iso27001_soc2_alignment.md:370-380 · type: stale
  The document says. §5 'what ForgeLM does NOT yet ship': 'SBOM exists; supply-chain CVE scanning does not'; '[tool.bandit] ... no workflow consumes it yet'.
  What the code does. The nightly workflow runs pip-audit with check_pip_audit.py, ci.yml and nightly run bandit with check_bandit.py, and the security extra exists. The doc's own Status line (L24) says implemented.
  Code references. .github/workflows/nightly.yml:264-334, .github/workflows/ci.yml:511-524, pyproject.toml:232-235
  Proposed correction. Retitle §5 "Gaps identified at design time (all closed in Faz 23)" and turn the present-tense denials into past tense, or delete them.

• DOC-D2B03-025 (docs, Medium) — docs/design/iso27001_soc2_alignment.md: stale — tests/test_sbom.py::test_deterministic / ::test_cyclonedx_schema_valid (also test_cyclonedx_1_5_schema_valid), tests/test_pip_audit_check.py, … severity **Medium** **Where.** [docs/design/iso27001_soc2_alignment.md:407-408](https://github.com/HodeTech/ForgeLM/blob/cab2947/docs/design/iso27001_soc2_alignment.md#L407-L408),438-442,503-505,638-640,680,734-739 · type: stale **The document says.** tests/test_sbom.py::test_deterministic/::test_cyclonedx_schema_valid(alsotest_cyclonedx_1_5_schema_valid), tests/test_pip_audit_check.py, tests/test_bandit_check.py, tests/test_bandit_clean.py; the SBOM is 'byte-identical' for the same tree and 'reproducible from the corresponding g… **What the code does.** None of those test files exist. The real tests are tests/test_supply_chain_security.py (TestGenerateSbomDeterministic::test_two_invocations_produce_same_content, ::test_required_cyclonedx_1_5_fields_present, TestCheckBandit) and tests/test_check_pip_audit.py. The determinism test compares content only after stripping serialNumber (a fresh uuid4) and the timestamp. No CycloneDX JSON-schema validat… **Code references.** [tests/test_supply_chain_security.py:54-147](https://github.com/HodeTech/ForgeLM/blob/cab2947/tests/test_supply_chain_security.py#L54-L147), [tests/test_supply_chain_security.py:271-403](https://github.com/HodeTech/ForgeLM/blob/cab2947/tests/test_supply_chain_security.py#L271-L403), [tests/test_supply_chain_security.py:481-515](https://github.com/HodeTech/ForgeLM/blob/cab2947/tests/test_supply_chain_security.py#L481-L515), [tests/test_check_pip_audit.py](https://github.com/HodeTech/ForgeLM/blob/cab2947/tests/test_check_pip_audit.py) **Proposed correction.** Cite the real tests and restate the contract: "SBOM content (excluding serialNumberandmetadata.timestamp`) is stable for the same Python environment; required CycloneDX 1.5 fields are asserted; no schema validation." Drop 'byte-identical' and 'reproducible from the git tag'.

• DOC-D2B03-026 (docs, Medium) — docs/design/iso27001_soc2_alignment.md: wrong detail — Nightly runs pip-audit --strict ... || true; suppressions live in tools/.pip-audit-ignore.json; 'high-severity findings exit 1; medium / low…
  severity Medium
  Where. docs/design/iso27001_soc2_alignment.md:451-465,683,856-858 · type: wrong detail
  The document says. Nightly runs pip-audit --strict ... || true; suppressions live in tools/.pip-audit-ignore.json; 'high-severity findings exit 1; medium / low emit warnings'; FAQ Q9: 'High-severity CVEs fail the nightly; medium / low warn.'
  What the code does. Nightly runs pip-audit --format json without --strict, then check_pip_audit.py --ignores tools/pip_audit_ignores.yaml (a YAML schema with id, package, reason, threat_model, verified_at, reevaluate_after). HIGH and CRITICAL fail, MEDIUM warns, LOW is silent, and UNKNOWN fails closed. pip-audit omits severity for nearly every advisory, so almost any finding fails the nightly.
  Code references. .github/workflows/nightly.yml:309-327, tools/check_pip_audit.py:7-24, tools/check_pip_audit.py:114-120, tools/pip_audit_ignores.yaml
  Proposed correction. "HIGH/CRITICAL and UNKNOWN-severity findings fail the nightly; MEDIUM emits ::warning::; LOW is silent. Project suppressions: tools/pip_audit_ignores.yaml (passed via --ignores)."

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