Align repo front door with final claim and reorganize legacy phase scripts

Author: Marcel

CLAIMS_AND_EVIDENCE.md

@@ -0,0 +1,22 @@
+# Claims and Evidence
+
+This table is the canonical mapping from research claims to exact artifacts and scripts.
+
+| Claim | Supported | Evidence Files | Producing Script(s) |
+|---|---|---|---|
+| Global H0/H1 summaries robustly predict correctness on GSM8K traces | **No** | `artifacts/paired_dynamic_qwen35/static_vs_dynamic_separability_2b.csv`; `artifacts/qwen35_2b_window_corrected/classifier_auc.csv` | `scripts/analyze_paired_dynamic.py`; `scripts/analyze_2b_window_corrected.py` |
+| Under fixed decoding, token-cap termination strongly predicts wrong answers | **Yes** | `artifacts/qwen35_2b_within_question/run_manifest.csv` | `scripts/run_multi_sample_questions.py` |
+| Cap sensitivity: longer budget rescues some capped failures but many remain wrong | **Yes** | `artifacts/qwen35_2b_cap_sensitivity_640/analysis/transition_summary.csv`; `artifacts/qwen35_2b_cap_sensitivity_640/analysis/per_question_transition_summary.csv` | `scripts/run_cap_sensitivity.py`; `scripts/analyze_cap_sensitivity.py` |
+| Micro-world decoder under-expresses `Unknown` | **Yes** | `artifacts/micro_world_v1/comparison_decoder_qwen_gemma.csv` | `scripts/run_micro_world_inference.py`; `scripts/analyze_micro_world_geometry.py` |
+| Verdict-region hidden states recover `Unknown` better than decoder outputs | **Yes** | `artifacts/micro_world_v1/comparison_probe_states_qwen_gemma.csv` | `scripts/run_micro_world_probe.py` |
+| Same-label vs different-label geometry gap is positive across worlds | **Yes** | `artifacts/micro_world_v1/analysis_qwen35_2b_partial19/sign_test_summary.csv`; `artifacts/micro_world_v1/analysis_gemma_3_4b_eval20_nothink/sign_test_summary.csv` | `scripts/analyze_micro_world_geometry.py` |
+| Constrained decoding fixes Unknown collapse | **No** | `artifacts/micro_world_v1/comparison_decoder_constrained_vs_unconstrained_qwen_gemma.csv` | `scripts/run_micro_world_inference.py`; comparison scripts in `artifacts/micro_world_v1` |
+| Gemma base-vs-instruct comparison after parse-confound repair still shows readout mismatch | **Yes** | `artifacts/micro_world_v1/comparison_gemma_base_prompt_rerun.csv`; `artifacts/micro_world_v1/comparison_probe_gemma_basefmt_vs_it_raw.csv` | `scripts/run_micro_world_inference.py`; `scripts/run_micro_world_probe.py` |
+| Verdict-step label logits under-rank `Unknown` on gold-Unknown decoder failures | **Yes** | `artifacts/micro_world_v1/comparison_label_logits_gemma_it_vs_pt_basefmt.csv` | `scripts/analyze_micro_world_label_logits.py` |
+| Layer sweeps show strong internal Unknown recoverability even when decoder fails | **Yes** | `artifacts/micro_world_v1/comparison_layer_sweep_gemma_it_vs_pt_basefmt.csv` | `scripts/run_micro_world_layer_sweep_probe.py` |
+
+## Main Paper Claim
+
+Supported by triangulation above:
+
+> On a held-out procedural micro-world task with nonce lexicons and held-out templates, `Unknown` / non-entailment is recoverable from verdict-region hidden states while decoder outputs under-express it; this dissociation replicates across Qwen and Gemma and survives prompt-path, constrained-decoding, logit, and layer-sweep controls.

PAPER_STATUS.md

@@ -0,0 +1,31 @@
+# Paper Status
+
+Current manuscript path:
+
+- Source: `paper/main.tex`
+- PDF: `paper/paper.pdf`
+
+Current framing:
+
+1. Phase A global topology branch is reported as a negative replication.
+2. Phase B fixed-decoding branch is reported as a convergence-failure result.
+3. Phase C micro-world branch is the main positive result:
+   representation--decoder dissociation for `Unknown`.
+
+What is included in the current draft:
+
+- Probe equation and protocol.
+- World-level geometry gap definition.
+- Verdict-step label-logit metrics.
+- Layer-sweep formulation.
+- Worked micro-world example table.
+- Exact artifact paths and reproduction commands.
+
+Build:
+
+```bash
+python3 paper/scripts/make_figures.py
+cd paper
+pdflatex -interaction=nonstopmode -halt-on-error main.tex
+pdflatex -interaction=nonstopmode -halt-on-error main.tex
+```

README.md

@@ -1,76 +1,44 @@
-# Topology of Truth (Consolidated Main)
+# Topology Repository
 
-This repository is now one merged branch with all experiments, artifacts, and paper outputs.
+This repo contains three completed experiment phases. The front-door claim is:
 
-## Project Status (short)
+> On a held-out procedural micro-world task, `Unknown` / non-entailment is recoverable from verdict-region hidden states, while decoder outputs under-express it.
 
-- The original global-topology hypothesis did **not** verify.
-- A fixed-decoding GSM8K branch found a strong **convergence-failure** effect.
-- A procedural micro-world branch found a replicated **representation--decoder dissociation** for `Unknown`.
+The old “global topology of truth” headline did not survive.
 
-## The 3 Experiment Tracks
+## Start Here
 
-1. **Old global H0/H1 topology (negative)**  
-   Details: [docs/experiments/01_global_h0_topology/README.md](docs/experiments/01_global_h0_topology/README.md)
-
-2. **Convergence failure on fixed GSM8K decoding (positive)**  
-   Details: [docs/experiments/02_convergence_failure/README.md](docs/experiments/02_convergence_failure/README.md)
-
-3. **Procedural micro-world semantics (main positive)**  
-   Details: [docs/experiments/03_micro_world_semantics/README.md](docs/experiments/03_micro_world_semantics/README.md)
-
-Index: [docs/experiments/README.md](docs/experiments/README.md)
-
-## Key Results
-
-### Track 1 (negative)
-
-- Dynamic/topology separability stayed weak (`AUC ~0.5-0.6`).
-- Corrected fixed-window topology did not beat controls (`AUC 0.20` vs controls `0.60`).
-
-### Track 2 (convergence)
-
-From `artifacts/qwen35_2b_within_question/run_manifest.csv`:
-
-- `n=180`, correct/wrong = `88/92`
-- capped = `87` (`75` wrong, `12` correct)
-- eos = `93` (`17` wrong, `76` correct)
-- cap->wrong AUC = `0.839`
+- Paper source: [paper/main.tex](paper/main.tex)
+- Paper PDF: [paper/paper.pdf](paper/paper.pdf)
+- Claim-to-file mapping: [CLAIMS_AND_EVIDENCE.md](CLAIMS_AND_EVIDENCE.md)
+- Repository file map: [REPO_MAP.md](REPO_MAP.md)
+- Experiment index: [docs/experiments/README.md](docs/experiments/README.md)
 
-From `artifacts/qwen35_2b_cap_sensitivity_640/analysis/transition_summary.csv`:
+## Three Phases
 
-- matched capped reruns = `87`
-- wrong->correct at longer budget = `27`
-- wrong->still wrong = `48`
+1. Phase A (negative): global H0/H1 topology on GSM8K traces  
+   [docs/experiments/01_global_h0_topology/README.md](docs/experiments/01_global_h0_topology/README.md)
 
-### Track 3 (micro-world)
+2. Phase B (positive): fixed-decoding convergence failure on GSM8K  
+   [docs/experiments/02_convergence_failure/README.md](docs/experiments/02_convergence_failure/README.md)
 
-Decoder baseline (`artifacts/micro_world_v1/comparison_decoder_qwen_gemma.csv`):
+3. Phase C (main positive): procedural micro-world representation–decoder dissociation  
+   [docs/experiments/03_micro_world_semantics/README.md](docs/experiments/03_micro_world_semantics/README.md)
 
-- Qwen3.5-2B Unknown recall = `0.000`
-- Qwen3.5-4B Unknown recall = `0.000`
-- Gemma-3-4B-it Unknown recall = `0.0125`
+## Main Numbers
 
-Verdict-token probe (`artifacts/micro_world_v1/comparison_probe_states_qwen_gemma.csv`):
+- Phase A: corrected topology-only AUC = `0.20` (controls = `0.60`)
+- Phase B: cap→wrong AUC = `0.839`; OR ≈ `26.40`
+- Phase C: decoder Unknown recall (`Qwen2B=0.000`, `Qwen4B=0.000`, `Gemma-it=0.0125`) while verdict-token probe Unknown recall (`0.7375`, `0.1292`, `0.5625`)
 
-- Qwen3.5-2B Unknown recall = `0.7375`
-- Qwen3.5-4B Unknown recall = `0.1292`
-- Gemma-3-4B-it Unknown recall = `0.5625`
+## Repo Notes
 
-## Paper and CI
-
-- Paper source: [paper/main.tex](paper/main.tex)
-- Compiled PDF: [paper/paper.pdf](paper/paper.pdf)
-- Figure generator: [paper/scripts/make_figures.py](paper/scripts/make_figures.py)
-- CI workflow: [.github/workflows/paper.yml](.github/workflows/paper.yml)
-- Release bundle script: [scripts/package_release_bundle.py](scripts/package_release_bundle.py)
+- Legacy root Python scripts were moved to `phase_a_global_h0_topology/scripts/`.
+- All committed artifacts are kept under `artifacts/` and `outputs/`.
+- `.npz` artifacts are committed (not ignored).
 
 ## Reproducibility
 
-- Version lock: [repro/requirements.lock.txt](repro/requirements.lock.txt)
-- Rebuild instructions: [repro/README.md](repro/README.md)
-
-## Artifact policy
-
-All committed artifacts are retained in-repo under `artifacts/` and `outputs/`.
-Release packaging additionally provides `release/paper_release_bundle.tar.gz` for a compact reproducible subset.
+- Locked deps: [repro/requirements.lock.txt](repro/requirements.lock.txt)
+- Rebuild guide: [repro/README.md](repro/README.md)
+- CI build/release: [.github/workflows/paper.yml](.github/workflows/paper.yml)

REPO_MAP.md

@@ -0,0 +1,79 @@
+# Repository Map
+
+This file maps the paper claims to concrete directories and entry points.
+
+## Top-level Layout
+
+- `README.md` — front-door summary and links.
+- `CLAIMS_AND_EVIDENCE.md` — claim-by-claim evidence table.
+- `docs/experiments/` — per-phase reproducibility docs.
+- `paper/` — manuscript (`main.tex`), PDF, figure pipeline.
+- `artifacts/` — committed run outputs used in analysis.
+- `outputs/` — additional generated outputs from legacy runs.
+- `repro/` — environment lock and rebuild notes.
+- `scripts/` — active analysis/generation scripts for Phases A/B/C.
+- `phase_a_global_h0_topology/scripts/` — legacy original root scripts (moved for clarity).
+
+## Experiment Phases
+
+### Phase A: Global Topology (Negative)
+
+- Doc: `docs/experiments/01_global_h0_topology/README.md`
+- Legacy scripts: `phase_a_global_h0_topology/scripts/`
+- Main artifacts:
+  - `artifacts/paired_dynamic_qwen35/`
+  - `artifacts/qwen35_2b_window_corrected/`
+
+### Phase B: Convergence Failure (Fixed Decoding)
+
+- Doc: `docs/experiments/02_convergence_failure/README.md`
+- Main scripts:
+  - `scripts/run_multi_sample_questions.py`
+  - `scripts/analyze_within_question_basins.py`
+  - `scripts/run_cap_sensitivity.py`
+  - `scripts/analyze_cap_sensitivity.py`
+- Main artifacts:
+  - `artifacts/qwen35_2b_within_question/`
+  - `artifacts/qwen35_2b_cap_sensitivity_640/`
+
+### Phase C: Micro-World Semantics (Main Result)
+
+- Doc: `docs/experiments/03_micro_world_semantics/README.md`
+- Main scripts:
+  - `scripts/generate_micro_world_dataset.py`
+  - `scripts/run_micro_world_inference.py`
+  - `scripts/analyze_micro_world_geometry.py`
+  - `scripts/run_micro_world_probe.py`
+  - `scripts/analyze_micro_world_label_logits.py`
+  - `scripts/run_micro_world_layer_sweep_probe.py`
+- Main artifacts:
+  - `artifacts/micro_world_v1/dataset/`
+  - `artifacts/micro_world_v1/generations/`
+  - `artifacts/micro_world_v1/comparison_*.csv`
+  - `artifacts/micro_world_v1/layer_sweep_*`
+  - `artifacts/micro_world_v1/label_logits_*`
+
+## Paper Assets
+
+- TeX source: `paper/main.tex`
+- Compiled PDF: `paper/paper.pdf`
+- Figure script: `paper/scripts/make_figures.py`
+- Generated figures: `paper/figures/`
+- CI workflow: `.github/workflows/paper.yml`
+- Release bundler: `scripts/package_release_bundle.py`
+
+## Legacy Script Location
+
+Legacy first-direction scripts previously kept at repo root are now under:
+
+- `phase_a_global_h0_topology/scripts/`
+
+This includes:
+
+- `audit_report.py`
+- `trace_generator.py`
+- `batch_verifier.py`
+- `topological_engine.py`
+- `analyze_results.py`
+- `visualizer.py`
+- `visualize_comparisons.py`

docs/experiments/01_global_h0_topology/README.md

@@ -11,6 +11,8 @@ This track is the direct test of that idea.
 
 - GSM8K examples from configured dataset loader.
 - Model generations and hidden states from Qwen3.5 0.8B/2B pilots.
+- Legacy first-pass pipeline scripts now live in:
+  - `phase_a_global_h0_topology/scripts/`
 
 ## Artifact generation pipeline
 

docs/experiments/02_convergence_failure/README.md

@@ -20,7 +20,7 @@ python3 scripts/run_multi_sample_questions.py \
   --model-id Qwen/Qwen3.5-2B \
   --question-start 0 \
   --question-count 20 \
-  --samples-per-question 5 \
+  --samples-per-question 9 \
   --temperature 0.7 \
   --top-p 0.95 \
   --max-new-tokens 384 \

paper/README.md

@@ -1,6 +1,7 @@
 # Paper Draft
 
-This directory contains a submission-style draft of the project report and the figure pipeline used by the manuscript.
+This directory contains the submission draft aligned with the current repository claim:
+the micro-world representation--decoder dissociation for `Unknown` is the main positive result; the GSM8K global-topology branch is a documented negative result.
 
 ## Files
 
@@ -21,3 +22,9 @@ pdflatex -interaction=nonstopmode -halt-on-error main.tex
 ```
 
 The GitHub workflow `.github/workflows/paper.yml` runs the same steps and uploads a release bundle.
+
+See also:
+
+- `../CLAIMS_AND_EVIDENCE.md`
+- `../REPO_MAP.md`
+- `../PAPER_STATUS.md`