Codebase hygiene + god-file decomposition (behavior-preserving)

audit-docs/allele_model_audit.md

@@ -39,7 +39,7 @@ The following Allele methods exist on every subclass:
 ### `_find_anchor`
 
 **Build-time only.** `_find_anchor` runs inside `Allele.__init__`
-when one of the bundled-data builders in `.private/scripts/`
+when one of the private bundled-data builder scripts
 constructs `VAllele("name", gapped_seq, length)` — the constructor
 calls `self._find_anchor()` unless `anchor_override=...` was passed.
 

audit-docs/docs_website_audit.md

@@ -92,11 +92,10 @@ sibling audits.
 | **Designs** (per-slice / per-mechanism scoping pre-implementation) | 17 | `clonal_family_design.md`, `clonal_parent_outcome_design.md`, `clonal_plan_split_design.md`, `d_inversion_design.md`, `d_inversion_extension_design.md`, `paired_end_design.md`, `receptor_revision_design.md`, `shm_segment_rate_design.md`, `v_subregion_shm_rate_design.md`, `np_markov_base_generator_design.md`, `p_nucleotide_design.md`, `fastq_export_design.md`, `allele_usage_estimation_design.md`, `trim_distribution_estimation_design.md`, `np_length_estimation_design.md`, `np_base_model_estimation_design.md`, `p_nucleotide_length_estimation_design.md` |
 | **Hubs / contributor entry points** | 6 | `engine_architecture.md`, `adding_a_pass.md`, `validation_matrix.md`, `reference_cartridge.md`, `airr_record_validator.md`, `allele_model_audit.md` |
 
-The `docs/superpowers/plans/` directory holds Claude-
-session planning artifacts (e.g.
-`2026-05-18-mcp-redesign-v2.md`) — **not user-facing
-documentation**, but currently mixed into the same
-`docs/` tree.
+A private planning directory holds pre-implementation
+planning notes (e.g. `2026-05-18-mcp-redesign-v2.md`) —
+**not user-facing documentation**, but currently mixed
+into the same `docs/` tree.
 
 The `docs/build/` directory holds Python wheel build
 artifacts (a side-effect of `python -m build`) — also
@@ -151,7 +150,6 @@ MkDocs Material lands.
 - `pin_scaffold_docs_dir_carries_thirty_eight_md_audit_design_files`
 - `pin_scaffold_old_docs_dir_exists_as_abandoned_earlier_attempt`
 - `pin_scaffold_deploy_docs_workflow_targets_website_dir`
-- `pin_scaffold_docs_superpowers_subdir_holds_session_artifacts_not_docs`
 - `pin_scaffold_docs_build_subdir_holds_wheel_artefacts_not_docs`
 
 ---
@@ -559,10 +557,10 @@ expand this audit.
   versioning; the MkDocs migration could add it (via
   `mike`). Decision belongs to the framework choice.
 - **Search backend.** Same — depends on framework choice.
-- **`docs/superpowers/plans/` cleanup.** The Claude-
-  session planning artefacts should probably move to a
-  separate `.private/` directory but that's a housekeeping
-  matter, not a docs structure issue.
+- **Private planning-notes cleanup.** The pre-implementation
+  planning notes should live in a separate private directory,
+  not under `docs/` — a housekeeping matter, not a docs
+  structure issue.
 
 ---
 

audit-docs/reference_cartridge_authoring_audit.md

@@ -74,10 +74,12 @@ in three places:
    "Populated by `RandomDataConfigBuilder.make_from_reference`",
    but `RandomDataConfigBuilder` is no longer importable
    anywhere in `src/GenAIRR/`.
-2. `.private/scripts/build_imgt_configs.py` still imports
-   `from GenAIRR.dataconfig.make.random import
-   RandomDataConfigBuilder` and is **currently broken** —
-   running it would `ModuleNotFoundError` at the top.
+2. The IMGT build script (historically a `.private/` script that
+   imported the removed `RandomDataConfigBuilder`) has since been
+   ported to a first-class, tracked maintainer tool at
+   `tools/build_imgt_configs.py`, built on
+   `ReferenceCartridgeBuilder`. The paragraphs below document the
+   interim broken-stub state that the port resolved.
 3. The build-cache mirror at
    `docs/build/lib.linux-x86_64-cpython-312/GenAIRR/dataconfig/make/`
    carries the historical implementation as a compile
@@ -129,7 +131,7 @@ reuse them rather than reinvent them.
 | Reference site | Pre-slice state | Post-slice state |
 |---|---|---|
 | [`dataconfig/data_config.py:159-166`](../src/GenAIRR/dataconfig/data_config.py#L159-L166) — `DataConfig.build_report` field docstring | "Populated by `RandomDataConfigBuilder.make_from_reference`" (named a removed class) | **[Cleaned]** Docstring now references `GenAIRR.cartridge_builder.ReferenceCartridgeBuilder.build`. Pinned by `test_pin_present_build_report_docstring_now_references_new_builder`. |
-| [`.private/scripts/build_imgt_configs.py`](../.private/scripts/build_imgt_configs.py) | `from GenAIRR.dataconfig.make.random import RandomDataConfigBuilder` — broken at module load with `ModuleNotFoundError` | **[Cleaned]** Top-level `raise NotImplementedError(...)` with explicit porting hint to `ReferenceCartridgeBuilder` + audit-doc reference; dead import moved into the unreachable function body for porting reference. Pinned by `test_pin_present_private_build_script_now_raises_explicit_legacy_error`. |
+| [`tools/build_imgt_configs.py`](../tools/build_imgt_configs.py) | The legacy build script imported the removed `from GenAIRR.dataconfig.make.random import RandomDataConfigBuilder` | **[Ported]** Rewritten as a first-class, tracked maintainer tool using `ReferenceCartridgeBuilder` (`from_fasta → infer_identity → infer_v_subregions → build`), producing structural cartridges. Pinned by `test_pin_present_imgt_build_tool_uses_reference_cartridge_builder` + `tests/test_build_imgt_configs.py`. |
 | `docs/build/lib.linux-x86_64-cpython-312/GenAIRR/dataconfig/make/...` | Historical implementation of `RandomDataConfigBuilder` / `CustomDataConfigBuilder` as a compile artefact | **Unchanged.** Build-cache mirror is not on the import path; regenerated by the next wheel build. Pinned absent by `test_pin_scaffold_historical_random_builder_module_is_gone` (verifies `ModuleNotFoundError` on import). |
 
 ### 3.2 Historical shape (for design inspiration only)
@@ -527,9 +529,9 @@ sub-steps:
    onto `cfg.build_report`).
 
 6. **Dead-reference cleanup**: update the
-   `DataConfig.build_report` docstring + update
-   `.private/scripts/build_imgt_configs.py` to import from
-   the new module.
+   `DataConfig.build_report` docstring + port the IMGT build
+   script to the new module (done: now
+   `tools/build_imgt_configs.py`).
 
 Cost estimate:
 
@@ -573,8 +575,8 @@ builder reuses
     every bundled cartridge (no producer in live source).
 11. `DataConfig.build_report` docstring still names
     `RandomDataConfigBuilder` — a dead class.
-12. `.private/scripts/build_imgt_configs.py` still imports
-    from the dead module path.
+12. The IMGT build script imported from the dead module path
+    (since ported to `tools/build_imgt_configs.py`).
 
 ### `pin_absence_*` — the gaps the slice closes
 
@@ -624,12 +626,11 @@ expand the work.
 - **Cartridge diff / merge tooling.** A future
   `CartridgeDiff` surface could compare two cartridges' build
   reports — separate slice.
-- **Live-data download (IMGT / OGRDB / etc.).** The
-  historical `.private/scripts/build_imgt_configs.py`
-  downloads FASTA from the web. The new builder accepts file
-  paths or pre-parsed allele lists; download tooling is a
-  separate concern (the private script can stay private,
-  updated to import the new builder).
+- **Live-data download (IMGT / OGRDB / etc.).** The IMGT
+  build tool (`tools/build_imgt_configs.py`) downloads FASTA
+  from the web. The builder itself accepts file paths or
+  pre-parsed allele lists; download tooling stays a separate
+  concern in the maintainer tool.
 - **GUI / web wrapper.** Out of scope.
 - **Auto-bundling.** The builder produces a `DataConfig`
   ready for pickling, but the wheel-build process that ships