wgl-suite — Weak-Gravitational-Lensing Substructure Research Suite

Single-project hub for cluster-scale weak-lensing substructure detection. Hosts all active Phase 2 work (Papers F / L / P + dz-cr exploration) and preserves the entire Phase 1 programme (Papers I-IV + D7 auxiliary) as a read-only archive.

Three repositories were consolidated into this single root on 2026-05-18 (weak-gravitational-lensing/ and wl-substructure-theory/ folded into wgl-suite/); the migration audit trail lives at archive/MIGRATION_LOG.md, the design plan at MIGRATION_PLAN.md.

---

Status

Phase	What	Where
Phase 1 (2024–early 2026)	Four-paper series + D7 auxiliary; frozen reference	archive/phase-1-source/, archive/phase-1-theory/, archive/phase-1-papers/; roster in archive/governance-phase1/PAPERS.md
Phase 2 (2026-05-06 onwards)	Three-paper restructuring: F (Foundations) / L (Letter) / P (Pipeline) + dz-cr exploratory letter; active	papers/F-foundations/, papers/L-letter/, papers/P-pipeline/, papers/dz-cr-letter/; framework in docs/decisions/PHASE_2.md

Phase-2 naming F / L / P locked by user decision D1 (2026-05-06). Architecture binding crystallised 2026-05-08 in D24–D27:

• D24: Paper F is pure-theoretical foundation; never depends on simulation or real-data results from this project.
• D25: Paper F's central narrative is the unified information- geometric framework on the cluster physical-state manifold $\mathcal{S}(x; z_l)$.
• D26: Paper L extends to a 4-coefficient boundary including the dz axis as sim-side feature on the post-D21 grid only. Real-data dz validation handed off to a user-led independent project.
• D27: Paper P adopts dz as the 20th per-peak raw feature (sim-trained); same hand-off for real-data dz validation.

Content state (2026-05-18 post-consolidation): F draft Iter-9 (29 pp, pure-theory locked); L draft v3 (7 pp, Phase-2 corrected anchors); P draft v2 mid-rewrite with Optuna sweep results pending; dz-cr-letter seeded but not yet drafted.

---

Phase-2 paper roster (locked names)

ID	Role	Origin in Phase 1	Workspace
Paper F	Foundations: pure-theory, unified information-geometric framework on $\mathcal{S}(x;z_l)$, Houston bound + DPI κ + dz $\sigma_{\Delta z}$ + DM Cramér-Rao	III + IV + D7	papers/F-foundations/
Paper L	Letter: 4-coefficient boundary (sub + sim-only dz extension) on post-D21 grid; n=14 zero-FP real-data sub validation	I (DBA) + dz axis	papers/L-letter/
Paper P	Pipeline: ACSDM ensemble with dz as 20th per-peak feature (sim-trained); hydro-mock + DES-Y1 + 4-noise + LSST-Y10 forecast	II (ACSDM) + dz channel	papers/P-pipeline/
dz-cr Letter	Exploratory: dz-only regression letter (A&A target); standalone of L's dz extension	D7 + Paper IV pilot	papers/dz-cr-letter/

Each workspace contains README + PLAN + DECISIONS + PROGRESS + OUTLINE files plus drafts/, figures/, scripts/, notes/ subdirectories. All per-paper decisions, plans, and progress are logged inside the paper's own directory to prevent memory drift.

The suite-level docs/PROJECT_PLAN.md is the single project-level entry point for the cross-paper architecture, sim regrid bundle (D21), and sequenced timeline. Per-paper PLAN.md files are subordinate to it.

---

Phase-1 archive (read-only)

Roman	Semantic	Canonical path
Paper I	DBA	archive/phase-1-papers/dba/main_v2.tex
Paper II	ACSDM	archive/phase-1-papers/acsdm/main_v6.tex
Paper III	Paper A	archive/phase-1-theory/paper/paperA/main.tex
Paper IV	Paper B	archive/phase-1-theory/paper/paperB/main.tex
D7 (auxiliary)	Depth-difference	archive/phase-1-papers/d7/main_v4.tex

Phase-2 sessions must not edit these. Numerical values imported from Phase 1 are re-verified against the canonical source in the same turn they enter Phase-2 text (CLAUDE.md R1, R2).

---

Repository layout (8 top-level categories)

wgl-suite/
├── CLAUDE.md                       ← session protocol (cc-enslaver + sci-paper)
├── README.md                       ← this file
├── MIGRATION_PLAN.md               ← 2026-05-18 consolidation plan (historical)
│
├── code/                           ← 1. CODE
│   ├── lib/                       ← installable Python packages
│   │   ├── wgl/                   ← Phase-2 package (was shared-lib/wgl_phase2)
│   │   └── substructure_lib/      ← Phase-1 lib mirror (COPY of archive)
│   ├── scripts/                   ← cross-paper + auxiliary scripts
│   │   ├── consolidate/           ← cross-paper consistency scripts
│   │   ├── experiments/           ← Phase-2 ad-hoc experiments (exp1–6, …)
│   │   └── simulation/            ← D21 sim bundle + diffusion training
│   └── notebooks/                 ← legacy notebooks (Phase-1 ACSDM workspace)
│
├── data/                           ← 2. DATA
│   ├── catalogs/                  ← real-data catalogs (LoVoCCS / DECADE / DES-Y1)
│   ├── sim/                       ← sim grids (d21, d21-archived)
│   ├── real/                      ← real-data products (parquet, mass-map, …)
│   ├── cache/                     ← augmented caches
│   ├── checkpoints/               ← model checkpoints (per-paper)
│   ├── ground-truth/              ← GT positions
│   └── misc/                      ← Xray, kinematic, etc.
│
├── references/                     ← 3. REFERENCES
│   ├── papers/                    ← read-only PDFs of cited literature
│   ├── bibtex/                    ← .bib files
│   └── notes/                     ← reading notes
│
├── papers/                         ← 4. PAPER WRITING (active Phase-2)
│   ├── F-foundations/             ← Paper F workspace
│   ├── L-letter/                  ← Paper L workspace
│   ├── P-pipeline/                ← Paper P workspace
│   └── dz-cr-letter/              ← dz Letter workspace
│   (each contains README + PLAN + DECISIONS + PROGRESS + OUTLINE
│    + drafts/ figures/ scripts/ notes/)
│
├── results/                        ← 5. RESULTS
│   ├── ablations/                 ← ablation_paper_results.json etc.
│   ├── loco/                      ← LOCO prediction tables
│   ├── stability/                 ← stability_sweep_results.json
│   ├── sweeps/                    ← optuna_sweep_results.json + Phase-1 sweeps
│   └── logs/                      ← cloud / auto-chain / general logs
│
├── figures/                        ← 6. FIGURES (cross-paper aggregated)
│   └── shared/                    ← cross-paper figures
│   (paper-specific figures live under papers/X/figures/)
│
├── docs/                           ← 7. DOCUMENTATION (governance)
│   ├── PROJECT_PLAN.md            ← current active plan (project-level entry)
│   ├── FACTS.md                   ← bedrock invariants
│   ├── KEY_NUMBERS.md             ← current measurements (mutable)
│   ├── PATHS.md                   ← auto-generated path inventory
│   ├── CODE_STANDARDS.md          ← modularity rules
│   ├── GAPS.md                    ← open items / G1-G10 backlog
│   ├── decisions/                 ← D-decision archive + Phase-2 sub-plans
│   │   ├── PHASE_2.md             ← Phase-2 framework + D1-D27 register
│   │   ├── PHASE_2_LAUNCH.md      ← Phase-2 launch checklist
│   │   └── PLAN_D21v2.md          ← D21 v2 sim regrid plan
│   ├── memory-phase1/             ← cc-memory session history (frozen)
│   └── working-notes/             ← Phase-1-era handoff notes (frozen)
│
└── archive/                        ← 8. ARCHIVE (preserved, never deleted)
    ├── MIGRATION_LOG.md           ← consolidation audit trail
    ├── phase-1-source/            ← was D:/Projects/weak-gravitational-lensing/
    ├── phase-1-theory/            ← was D:/Projects/wl-substructure-theory/
    ├── phase-1-papers/            ← compiled Phase-1 manuscripts
    ├── governance-phase1/         ← Phase-1 governance (ROADMAP / PAPERS / …)
    ├── draft-iterations/          ← compile logs + old draft revisions
    └── brainstorm/                ← brainstorm outputs from F / L / dz-cr

Document classification (governance)

Class	Files	Editing policy
Session protocol	CLAUDE.md, docs/CODE_STANDARDS.md	edited only when standards change
Inventory	docs/PATHS.md, README.md	PATHS.md AUTO blocks regenerate; README hand-curated
Bedrock (immutable)	docs/FACTS.md	theorems / definitions / locked D-decisions / file paths
Measurements (mutable)	docs/KEY_NUMBERS.md	fits / AUC / F1 / ablations; refreshes after re-fit
Phase-2 governance	docs/PROJECT_PLAN.md, docs/decisions/PHASE_2.md	PROJECT_PLAN = entry point; PHASE_2 = decisions D1-D27
Phase-2 backlog	docs/GAPS.md	open items G1-G10
Phase-1 archive (frozen)	archive/governance-phase1/	append-only
Per-paper	papers/{F-foundations,L-letter,P-pipeline,dz-cr-letter}/{README,PLAN,DECISIONS,PROGRESS,OUTLINE}.md + subdirs	per-paper R3 contract
Shared infra	code/lib/, code/scripts/	code via CODE_STANDARDS R4
Working notes (frozen)	docs/working-notes/	append-only; archived intake logs

---

Mandatory standards (every session)

1. CLAUDE.md — auto-loaded; defines session protocol. Read on every session start.
2. docs/PATHS.md — synchronously updated with every structural change.
3. docs/CODE_STANDARDS.md — modularity rules; Phase-2 scripts import via wgl (was wgl_phase2).
4. Per-paper DECISIONS.md / PROGRESS.md — every decision and progress entry recorded in the paper's own directory.
5. cc-enslaver throughout: seven-question check (Rule 02) on start, four-step convergence + fidelity check (Rules 06, 07) at end.
6. sci-paper plugin throughout: drafting / brainstorm / review / figure-QA via the plugin's slash commands.

---

Consistency-check usage

# Verify all cross-paper cite keys resolve
python code/scripts/consolidate/check_cross_refs.py

# Verify shared numerical values still match canonical sources
python code/scripts/consolidate/check_key_numbers.py

# Regenerate docs/PATHS.md AUTO blocks from disk scan
python code/scripts/consolidate/extract_paths.py --generate

# Verify docs/PATHS.md hasn't drifted from the on-disk layout
python code/scripts/consolidate/extract_paths.py --check

All three must pass before any Phase-2 commit that touches numbers, citations, or the file layout.

---

License

Internal research project; no external license. Citations of the underlying papers should reference each paper's own canonical citation key (dba_paper, acsdm_paper, paperA, paperB), not this suite.