Full-project review remediation: 163 findings + generation-based Llama-Guard + two-pass Opus/Sonnet review

.github/workflows/ci.yml

@@ -14,10 +14,16 @@ on:
 env:
   FORGELM_OPERATOR: ci-smoke
 
+# No workflow-level permissions; each job declares the minimum it needs
+# (checkout-only read access), per Sonar githubactions:S8233 / S8264 —
+# matches the pattern in nightly.yml / publish.yml / site-deploy.yml.
+
 jobs:
   # --- Job 1: Lint (fast, no heavy deps) ---
   lint:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
       - uses: actions/checkout@v5
 
@@ -58,6 +64,8 @@ jobs:
   # --- Job 2: Test (matrix across Python versions) ---
   test:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     strategy:
       fail-fast: false
       matrix:
@@ -71,9 +79,18 @@ jobs:
           cache: pip
 
       - name: Install package (dev)
+        # `ingestion-scale` (datasketch) is included so
+        # tests/test_data_audit_phase12.py::TestMinHashLshDedup — which
+        # `skipif`s itself when the real library is absent — actually runs
+        # the genuine MinHash/MinHashLSH backend on every push/PR across
+        # all four Python versions, not just the pure-Python stub coverage
+        # in TestMinHashLshBackendExecutedWithStub. datasketch is a light
+        # numpy/scipy-based dep, not one of the heavy extras (bitsandbytes,
+        # unsloth, deepspeed, lm-eval, wandb, mergekit) that stay off the
+        # default test matrix.
         run: |
           python -m pip install --upgrade pip
-          python -m pip install -e ".[dev]"
+          python -m pip install -e ".[dev,ingestion-scale]"
 
       - name: Run tests with coverage
         # --cov, --cov-report=term-missing, and --cov-fail-under=40 come from
@@ -92,6 +109,8 @@ jobs:
   # --- Job 3: Validate (config, CLI, assets) ---
   validate:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
       - uses: actions/checkout@v5
 
@@ -280,6 +299,16 @@ jobs:
         # real doc-vs-schema drift.
         run: python3 tools/check_yaml_snippets.py --strict
 
+      - name: User-manual YAML example schema-key drift
+        # check_yaml_snippets.py only validates snippets carrying the full
+        # model+training+data triplet; single-block fragments (the common
+        # case in a user-manual page explaining one section) are skipped
+        # there. This guard AST-walks forgelm/config.py's Pydantic schema
+        # and flags fragment keys that don't exist on it. Runs with --strict:
+        # the introduction-time fabricated-key backlog (38 instances across 8
+        # EN/TR page-pairs) has been cleaned, so any new drift now fails CI.
+        run: python3 tools/check_usermanual_schema_drift.py --strict
+
       - name: Site chrome (EN/TR translation) parity
         # W1/H11 (F-P8-C-07): the active-tier (EN<->TR) translation-key sets in
         # site/js/translations.js must stay in lockstep. Run WITHOUT --strict:

.github/workflows/usermanuals-validate.yml

@@ -22,9 +22,15 @@ on:
 env:
   FORGELM_OPERATOR: ci-smoke
 
+# No workflow-level permissions; the job declares the minimum it needs
+# (checkout-only read access), per Sonar githubactions:S8233 / S8264 —
+# matches the pattern in nightly.yml / publish.yml / site-deploy.yml.
+
 jobs:
   validate:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
       - uses: actions/checkout@v5
 

AGENTS.md

@@ -46,7 +46,7 @@ Each skill's `SKILL.md` has the full checklist. Follow it; don't skip steps to s
 
 ```text
 ForgeLM/
-├── forgelm/                 # Source code: ~22 single-file modules + 2 sub-packages
+├── forgelm/                 # Source code: ~22 single-file modules + 3 sub-packages
 │   ├── cli/                 # CLI package (Phase 15 split): _parser, _dispatch,
 │   │                        # _exit_codes, subcommands/{ingest, audit, chat,
 │   │                        # export, deploy, quickstart, doctor, cache,
@@ -57,6 +57,8 @@ ForgeLM/
 │   │                        # _aggregator, _streaming, _simhash, _minhash,
 │   │                        # _pii_regex, _pii_ml, _secrets, _quality,
 │   │                        # _croissant, _summary, _splits
+│   ├── wizard/              # Interactive --wizard config generation: _collectors,
+│   │                        # _orchestrator, _state, _byod, _io, _defaults.json
 │   ├── config.py            # Pydantic schemas (23 models)
 │   ├── trainer.py           # TRL wrapper (SFT/DPO/SimPO/KTO/ORPO/GRPO)
 │   ├── model.py             # HF + PEFT model loading
@@ -68,7 +70,7 @@ ForgeLM/
 │   ├── grpo_rewards.py      # Built-in GRPO format/length shaping reward fallback
 │   ├── _http.py             # SSRF-guarded HTTP chokepoint (safe_post / safe_get)
 │   ├── _version.py          # `__version__` + `__api_version__` (decoupled)
-│   └── ...                  # benchmark, judge, merging, synthetic, wizard,
+│   └── ...                  # benchmark, judge, merging, synthetic,
 │                            # quickstart, model_card, fit_check, deploy, chat,
 │                            # export, inference, results, utils
 ├── tests/                   # 70 test modules; count grows over time (run `pytest --collect-only -q` for current)
@@ -113,7 +115,7 @@ These come from the standards documents; summarized here for quick reference:
 
 ## What ForgeLM is not
 
-Reinforced in [docs/marketing/strategy/05-yapmayacaklarimiz.md](docs/marketing/strategy/05-yapmayacaklarimiz.md). Do not propose or implement:
+Reinforced in the internal marketing strategy notes (`docs/marketing/strategy/05-yapmayacaklarimiz.md`, gitignored, not present in this checkout). Do not propose or implement:
 
 - **Web UI / GUI.** Config-driven is the identity. Dashboard for Pro CLI only.
 - **Custom inference engine.** Hand off to Ollama / vLLM / TGI / llama.cpp.
@@ -161,10 +163,15 @@ Default workflow for a non-trivial change:
      python3 tools/check_tr_links_prefer_mirror.py --strict && \
      python3 tools/check_usermanual_self_contained.py --strict && \
      python3 tools/check_notebook_pins.py --strict && \
+     python3 tools/check_usermanual_schema_drift.py --strict && \
      python3 tools/update_site_version.py --check
    ```
 
-   All fifteen must pass. The first four are the historical gauntlet;
+   All sixteen must pass (the usermanual-schema-drift guard —
+   `check_usermanual_schema_drift.py --strict` — validates that every
+   fenced YAML key under `docs/usermanuals/` resolves against the real
+   `ForgeConfig` schema, catching fabricated-field examples that would
+   fail `--dry-run`). The first four are the historical gauntlet;
    the three doc guards (Wave 3 / Wave 4 / Wave 5 additions) catch
    bilingual structural drift, broken markdown anchors, and CLI ↔ docs
    help-text drift before the PR opens. The wizard-defaults guard
@@ -226,7 +233,7 @@ Default workflow for a non-trivial change:
 
 - The `docs/marketing/` directory is gitignored (internal strategy). Content there is real; treat it as a source of truth for direction but don't reference it in public-facing code or docs.
 - The `docs/analysis/` directory is gitignored research / audit working memory (PR-cycle review notes, external-repo comparisons, drafts). **Never reference its contents from production code, public docs, CHANGELOG entries, commit messages, or PR descriptions.** Decisions distilled from those notes live in `docs/standards/`, `docs/roadmap/`, the CHANGELOG, and inline code comments — those are the citations reviewers see.
-- The roadmap ([docs/roadmap.md](docs/roadmap.md)) is what ships. The marketing strategy roadmap ([docs/marketing/marketing_strategy_roadmap.md](docs/marketing/marketing_strategy_roadmap.md)) is what gets announced. Don't conflate the two.
+- The roadmap ([docs/roadmap.md](docs/roadmap.md)) is what ships. The marketing strategy roadmap (`docs/marketing/marketing_strategy_roadmap.md`, gitignored, not present in this checkout) is what gets announced. Don't conflate the two.
 
 ---