Finalize paper narrative and evidence docs

README.md

@@ -136,6 +136,54 @@ scripts/slurm/submit_kerneltuner.sh \
   --mem 24GB
 ```
 
+## Slurm Submission Helpers
+
+For cluster execution, the repo includes reusable Slurm scripts:
+
+- `scripts/slurm/run_kerneltuner_array.sbatch`: array worker that maps one array task to one experiment YAML.
+- `scripts/slurm/submit_kerneltuner.sh`: submit wrapper that computes array size from a list file.
+
+Example list file:
+
+- `configs/experiments/slurm_experiment_list.example.txt`
+
+Basic usage:
+
+```bash
+chmod +x scripts/slurm/submit_kerneltuner.sh
+cp configs/experiments/slurm_experiment_list.example.txt configs/experiments/slurm_experiment_list.txt
+scripts/slurm/submit_kerneltuner.sh \
+  --list configs/experiments/slurm_experiment_list.txt \
+  --partition gpunodes \
+  --gpu-type rtx_a2000 \
+  --gpus 1 \
+  --time 0-04:00 \
+  --cpus 4 \
+  --mem 24GB \
+  --log-dir /scratch/scratch-space/expires-xxxx/$USER/kerneltuner_logs \
+  --scratch-root /scratch/scratch-space/expires-xxxx/$USER/kerneltuner \
+  --artifact-root /scratch/scratch-space/expires-xxxx/$USER/kerneltuner_artifacts \
+  --mail-user [email protected] \
+  --mail-type BEGIN,END,FAIL \
+  --alert-email [email protected] \
+  --alert-on-start
+```
+
+Useful environment overrides:
+
+- `RUN_COMMAND_TEMPLATE` (default: `ktune run-experiment --experiment "{experiment}"`)
+- `INSTALL_PACKAGES` (`0` to skip pip install in jobs)
+- `EXTRA_PIP_PACKAGES` (space-separated extra pip packages)
+- `SKIP_IF_ARTIFACTS_EXIST` (`0` to force reruns)
+- `DRY_RUN=1` (worker-level dry run)
+- `ALERT_EMAIL`, `ALERT_ON_START`, `ALERT_ON_END`, `ALERT_ON_FAIL` for worker-level alerts
+
+Notes:
+
+- `--artifact-root` overrides `artifact_root` in experiment YAML at submission time.
+- If no scratch path exists on the node, jobs fall back to `<workspace>/.scratch/$USER`.
+- Slurm native email (`--mail-user/--mail-type`) and worker-level alerts can be used together.
+
 ## What This Repo Is Not
 
 - It is not a Triton compiler redesign effort.

docs/research/00_index.md

@@ -42,9 +42,9 @@ Current project phase:
 - the completed Phase 3 execution analysis is [logs/2026-03-29_phase3_execution_analysis.md](logs/2026-03-29_phase3_execution_analysis.md)
 - the completed R6 final synthesis and evidence lock is [logs/2026-03-30_r6_final_synthesis_and_evidence_lock.md](logs/2026-03-30_r6_final_synthesis_and_evidence_lock.md)
 - the earlier documentation freeze point remains recorded in [logs/2026-03-28_phase3_documentation_boundary.md](logs/2026-03-28_phase3_documentation_boundary.md) as historical context only
-- the canonical reusable Phase 2 artifact summary lives under `artifacts/analysis/phase2_20260327/`
-- the canonical reusable Phase 3 artifact summary lives under `artifacts/analysis/phase3_20260329/`
-- the canonical final paper-evidence bundle lives under `artifacts/analysis/final_paper_20260330/`
+- for paper writing and verification in this repo snapshot, treat `docs/research/`, `docs/adr/`, and `logs/` as the canonical documentation backbone
+- use the evidence registry, final claim inventory, and dated analysis logs as the primary source of truth for promoted claims
+- treat older references to `artifacts/analysis/...` as historical pointers rather than required local dependencies for reading the paper backbone
 - the completed bounded R6 batch is now promoted; no further selector-family expansion is justified inside the current paper backbone
 
 ## Reading Order

paper/CLAIM_VERIFICATION.md

@@ -0,0 +1,109 @@
+# Claim Verification Notes
+
+This note records the post-edit verification pass for the current manuscript.
+
+## Verification Scope
+
+Verified against:
+
+- `docs/research/11_final_claim_inventory.md`
+- `docs/research/08_evidence_registry.md`
+- `docs/research/12_related_work_and_positioning.md`
+- `docs/adr/ADR-001-single-host-single-gpu.md`
+- `docs/adr/ADR-004-matched-budget-evaluation.md`
+- `paper/DRAFT_CHECKLIST.md`
+- `paper/appendix/extended_results.tex`
+- dated execution-analysis logs under `docs/research/logs/`
+
+Primary paper sections checked:
+
+- `paper/sections/abstract.tex`
+- `paper/sections/introduction.tex`
+- `paper/sections/results.tex`
+- `paper/sections/discussion.tex`
+- `paper/sections/conclusion.tex`
+
+## Main Outcome
+
+The current manuscript stays within the locked paper-safe claim set.
+
+The core claim structure is consistent across abstract, introduction, results, discussion, and conclusion:
+
+- cheap compile-adjacent signals help with pruning more than ranking,
+- aligned GEMM is supporting context rather than the truth source,
+- LayerNorm is a bounded regime-split secondary result,
+- revised selectors are a mixed transfer story rather than a universal success,
+- `H5` remains the unsupported Phase 3 `split_k` result,
+- and the final non-`split_k` mainline result is a bounded positive headline.
+
+## Numeric Claims Checked
+
+The following main-text numbers were checked against the evidence registry and dated logs:
+
+- Phase 2 representative GEMM:
+  - `naive_random_search = 1.0331`
+  - `prune_rank = 0.8265`
+  - `prune_rank_profiled = 0.8444`
+- Phase 2 aligned GEMM:
+  - `prune_rank = 0.8795`
+  - `prune_rank_profiled = 0.8873`
+  - `naive_random_search = 0.9951`
+- Phase 2 LayerNorm:
+  - `small_batch`: `1.0100` vs `1.0113`
+  - `large_batch`: `1.0029` vs `0.9856`
+- Phase 3 `split_k` result:
+  - parent `prune_rank = 1.0324`
+  - `naive_random_search = 1.0427`
+  - `v4_transfer_safe_profiled = 0.1609`
+  - ablation values `0.1622`, `0.1623`, and parent `0.9692`
+- Final R6 mainline:
+  - parent `prune_rank = 0.8101`
+  - `naive_random_search = 1.0011`
+  - `v5_mainline_profiled = 1.0286`
+  - improvement over parent `0.2185`
+
+## Checklist Status
+
+Checked and satisfied in the current source:
+
+- every main-text claim matches the final claim inventory or a weaker paraphrase
+- `H5` is still written only as the unsupported Phase 3 `split_k` result
+- `R6` is still written as a bounded improvement, not a universal win
+- LayerNorm remains secondary and regime-split
+- introduction, abstract, results, discussion, and conclusion now tell the same final story
+- appendices remain chronology/provenance oriented rather than introducing new promoted claims
+
+## Documentation Backbone Used For Verification
+
+For this workspace snapshot, the paper backbone should be treated as:
+
+- `docs/research/` for claims, interpretation, and experiment history,
+- `docs/adr/` for fixed environment and evaluation decisions,
+- and `docs/research/logs/` for the chronological execution record.
+
+The artifact bundle paths referenced in older documentation are not the primary verification source in this checkout.
+
+This verification pass is therefore grounded in:
+
+- the claim ledger,
+- the evidence registry,
+- the related-work and paper-outline research docs,
+- the relevant ADRs,
+- appendix artifact mappings,
+- and the dated analysis logs.
+
+That is strong enough to verify that the manuscript stays consistent with the repo's documented evidence backbone.
+
+## Paper Build Status
+
+The paper compiles successfully with:
+
+- `tectonic -X compile main.tex`
+
+Current output:
+
+- `paper/main.pdf`
+
+Known remaining issue:
+
+- the PDF still has many table and appendix line-breaking warnings (`Underfull` / `Overfull` boxes), but the build succeeds and the references now start on a new page.

paper/FIGURE_MANIFEST.md

@@ -3,8 +3,8 @@
 | Figure | Purpose | Source Artifact | Claim IDs | Draft Status |
 | --- | --- | --- | --- | --- |
 | Figure 1 | Conceptual overview of the \system pipeline from candidate generation to final evidence | Derived from `docs/research/04_signal_and_profiling_plan.md`, `docs/research/06_hypotheses_and_ablation_plan.md`, and `docs/specs/` | `C-FINAL-H1`, `C-FINAL-HEADLINE` | LaTeX-native conceptual schematic |
-| Figure 2 | Final representative GEMM headline comparison | `artifacts/analysis/final_paper_20260330/figure_source_map.csv` row `F1` | `C-FINAL-HEADLINE` | LaTeX-native numeric figure |
-| Figure 3 | Aligned vs representative GEMM context | `artifacts/analysis/final_paper_20260330/figure_source_map.csv` row `F2` | `C-FINAL-H1`, `C-FINAL-H3` | LaTeX-native numeric figure |
-| Figure 4 | LayerNorm regime split | `artifacts/analysis/final_paper_20260330/figure_source_map.csv` row `F3` | `C-FINAL-H2`, `C-FINAL-ROWS` | LaTeX-native numeric figure |
-| Figure 5A | Final mainline selector ablation | `artifacts/analysis/final_paper_20260330/figure_source_map.csv` row `F7` | `C-FINAL-HEADLINE`, `C-FINAL-H4`, `C-FINAL-CLOSEOUT` | LaTeX-native numeric panel |
-| Figure 5B | Chosen-family vs best-family diagnostic | `artifacts/analysis/final_paper_20260330/figure_source_map.csv` row `F11` | `C-FINAL-H5`, `C-FINAL-SPLITK` | LaTeX-native diagnostic panel |
+| Figure 2 | Final representative GEMM headline comparison | `docs/research/08_evidence_registry.md`, `docs/research/11_final_claim_inventory.md`, `docs/research/logs/2026-03-30_r6_final_synthesis_and_evidence_lock.md` | `C-FINAL-HEADLINE` | LaTeX-native numeric figure |
+| Figure 3 | Aligned vs representative GEMM context | `docs/research/08_evidence_registry.md`, `docs/research/11_final_claim_inventory.md`, `docs/research/logs/2026-03-27_phase2_execution_analysis.md` | `C-FINAL-H1`, `C-FINAL-H3` | LaTeX-native numeric figure |
+| Figure 4 | LayerNorm regime split | `docs/research/08_evidence_registry.md`, `docs/research/11_final_claim_inventory.md`, `docs/research/logs/2026-03-27_phase2_execution_analysis.md`, `docs/research/logs/2026-03-29_phase3_execution_analysis.md` | `C-FINAL-H2`, `C-FINAL-ROWS` | LaTeX-native numeric figure |
+| Figure 5A | Final mainline selector ablation | `docs/research/08_evidence_registry.md`, `docs/research/11_final_claim_inventory.md`, `docs/research/logs/2026-03-30_r6_final_synthesis_and_evidence_lock.md` | `C-FINAL-HEADLINE`, `C-FINAL-H4`, `C-FINAL-CLOSEOUT` | LaTeX-native numeric panel |
+| Figure 5B | Chosen-family vs best-family diagnostic | `docs/research/08_evidence_registry.md`, `docs/research/11_final_claim_inventory.md`, `docs/research/logs/2026-03-29_phase3_execution_analysis.md` | `C-FINAL-H5`, `C-FINAL-SPLITK` | LaTeX-native diagnostic panel |

paper/OLD_PDF_DELTA.md

@@ -0,0 +1,72 @@
+# Old PDF vs Current Source
+
+This note records the selective review of the checked-in `CSC2210H_Project.pdf` against the current LaTeX source in `paper/`.
+
+## Status of the checked-in PDF
+
+- The checked-in PDF is an older snapshot created on March 22, 2026.
+- It is only 3 pages long.
+- It still contains placeholder front matter, including the title `TITLE`.
+- It should not be treated as the current source of truth.
+
+The current paper state is the LaTeX source rooted at `paper/main.tex`.
+
+## Front Matter Mismatch
+
+The strongest mismatch is the front matter:
+
+- old PDF title: `TITLE`
+- current source title: `Bottleneck-Aware Schedule-First Tuning for Triton Kernels Under Matched Budget`
+- old PDF author line: `Pedram` and `Giovanni Galea Curmi`
+- current source author line: `Project Draft`
+
+The old PDF therefore captures an earlier milestone, not the present manuscript state.
+
+## What Exists Locally But Not in the Old PDF
+
+The old PDF contains an early short draft with an introduction, related-work framing, and references. The current source now includes a full manuscript structure:
+
+- abstract,
+- introduction,
+- background and problem setting,
+- system design,
+- experimental methodology,
+- results,
+- discussion and limitations,
+- related work,
+- conclusion,
+- and appendices for methods, results, and provenance.
+
+The current source also includes the main paper tables, figure manifest, table manifest, and section index used to keep the draft aligned with the evidence bundle.
+
+## What the Old PDF Still Does Well
+
+The old PDF has a few writing choices worth preserving because they are direct and easy to follow:
+
+- It states the narrow project question early.
+- It explains the paper's "middle ground" positioning in simple language.
+- It plainly says what the project is not trying to do: redesign Triton, replace vendor libraries, or generate kernels from scratch.
+- It introduces the practical tuning problem before moving into literature positioning.
+
+These choices should remain visible in the current source even as the manuscript becomes more complete.
+
+## Wording Worth Preserving Selectively
+
+The following phrasing patterns from the old PDF are worth keeping when they fit naturally:
+
+- "keeps the Triton kernel fixed"
+- "a narrower but still meaningful question"
+- "under the same budget"
+- explicit contrasts such as "not redesign Triton" and "not generate new kernels from scratch"
+
+These phrases are useful because they set scope quickly and avoid inflated language.
+
+## Main Difference in Writing Density
+
+The current source is more complete and scientifically stronger, but it is also denser than the old PDF in some places, especially in `Results` and `Discussion`.
+
+The editing goal is therefore:
+
+- keep the newer evidence-backed structure,
+- preserve the clearer scope-setting language from the old PDF when helpful,
+- and avoid drifting into a more compressed research voice than the paper needs.

paper/SECTION_INDEX.md

@@ -2,17 +2,17 @@
 
 This file maps manuscript sections to the source docs, canonical artifacts, claim IDs, and figure/table IDs used in the first draft.
 
-| Manuscript Section | Primary Source Docs | Primary Artifacts | Claim IDs | Figures / Tables |
+| Manuscript Section | Primary Source Docs | Primary Supporting Sources | Claim IDs | Figures / Tables |
 | --- | --- | --- | --- | --- |
-| Abstract | `docs/research/01_research_program.md`, `docs/research/11_final_claim_inventory.md` | `artifacts/analysis/final_paper_20260330/final_bundle_summary.md` | `C-FINAL-HEADLINE`, `C-FINAL-H2`, `C-FINAL-H5` | none |
-| Introduction | `docs/research/01_research_program.md`, `docs/research/11_final_claim_inventory.md`, `docs/research/12_related_work_and_positioning.md` | `artifacts/analysis/final_paper_20260330/final_claim_table.csv` | `C-FINAL-HEADLINE`, `C-FINAL-H1`, `C-FINAL-H4`, `C-FINAL-CLOSEOUT` | `T1` |
-| Background and Problem Setting | `docs/research/02_tuning_theory_and_knob_space.md`, `docs/research/03_bottleneck_taxonomy.md`, `docs/research/05_workload_matrix_and_case_studies.md`, `docs/research/12_related_work_and_positioning.md` | final claim bundle and final figure map | `C-FINAL-H1`, `C-FINAL-H3` | `T2`, `T3`, Figure 1 |
-| KernelTuner Design | `docs/research/04_signal_and_profiling_plan.md`, `docs/research/06_hypotheses_and_ablation_plan.md` | final bundle, final configs | `C-FINAL-SPLITK`, `C-FINAL-ROWS` | Figure 1, `T2` |
-| Experimental Methodology | `docs/research/05_workload_matrix_and_case_studies.md`, `docs/research/07_experiment_campaign_plan.md`, `docs/research/08_evidence_registry.md` | `artifacts/analysis/final_paper_20260330/canonical_artifact_map.csv` | all final claims indirectly | `T1`, `T3` |
+| Abstract | `docs/research/01_research_program.md`, `docs/research/11_final_claim_inventory.md` | evidence registry plus final synthesis log | `C-FINAL-HEADLINE`, `C-FINAL-H2`, `C-FINAL-H5` | none |
+| Introduction | `docs/research/01_research_program.md`, `docs/research/11_final_claim_inventory.md`, `docs/research/12_related_work_and_positioning.md` | final claim inventory and ADR-backed scope decisions | `C-FINAL-HEADLINE`, `C-FINAL-H1`, `C-FINAL-H4`, `C-FINAL-CLOSEOUT` | `T1` |
+| Background and Problem Setting | `docs/research/02_tuning_theory_and_knob_space.md`, `docs/research/03_bottleneck_taxonomy.md`, `docs/research/05_workload_matrix_and_case_studies.md`, `docs/research/12_related_work_and_positioning.md` | research backbone docs and workload program | `C-FINAL-H1`, `C-FINAL-H3` | `T2`, `T3`, Figure 1 |
+| Related Work | `docs/research/12_related_work_and_positioning.md` plus bibliography | literature positioning doc and bibliography | none directly | `T8` indirectly |
+| KernelTuner Design | `docs/research/04_signal_and_profiling_plan.md`, `docs/research/06_hypotheses_and_ablation_plan.md` | research plan plus ADR decisions on scope and evaluation | `C-FINAL-SPLITK`, `C-FINAL-ROWS` | Figure 1, `T2` |
+| Experimental Methodology | `docs/research/05_workload_matrix_and_case_studies.md`, `docs/research/07_experiment_campaign_plan.md`, `docs/research/08_evidence_registry.md`, `docs/adr/ADR-004-matched-budget-evaluation.md` | methodology and evaluation docs | all final claims indirectly | `T1`, `T3` |
 | Results 6.1 | `docs/research/08_evidence_registry.md`, `docs/research/11_final_claim_inventory.md` | `gemm_v2_baseline_mapping`, `gemm_v2_aligned_reference` | `C-FINAL-H1`, `C-FINAL-H3` | Figure 3, `T4` |
 | Results 6.2 | `docs/research/08_evidence_registry.md`, `docs/research/11_final_claim_inventory.md` | `layernorm_v2_small_regime`, `layernorm_v2_large_regime`, Phase 3 microstudy rows | `C-FINAL-H2`, `C-FINAL-ROWS` | Figure 4, `T4` |
 | Results 6.3 | `docs/research/08_evidence_registry.md`, `docs/research/09_opportunity_log.md`, `docs/research/11_final_claim_inventory.md` | `h4_retry_g3`, `gemm_v3_baseline_mapping`, `gemm_v3_selector_ablation`, `gemm_v3_schedule_diag` | `C-FINAL-H4`, `C-FINAL-H5`, `C-FINAL-SPLITK` | Figure 5, `T4` |
 | Results 6.4 | `docs/research/11_final_claim_inventory.md`, `docs/research/logs/2026-03-30_r6_final_synthesis_and_evidence_lock.md` | `gemm_final_baseline_mapping`, `gemm_final_selector_ablation` | `C-FINAL-HEADLINE`, `C-FINAL-CLOSEOUT` | Figure 2, Figure 5, `T4` |
-| Discussion / Limitations | `docs/research/01_research_program.md`, `docs/research/08_evidence_registry.md`, `docs/research/11_final_claim_inventory.md` | final paper bundle | all final claims | none |
-| Related Work | `docs/research/12_related_work_and_positioning.md` plus bibliography | bibliography | none directly | `T8` indirectly |
-| Appendix | dated logs and final bundle | `artifacts/analysis/final_paper_20260330/`, phase2 and phase3 bundles | all final claims | appendix-only tables |
+| Discussion / Limitations | `docs/research/01_research_program.md`, `docs/research/08_evidence_registry.md`, `docs/research/11_final_claim_inventory.md` | claim ledger, evidence registry, and ADR-backed limits | all final claims | none |
+| Appendix | dated logs, research docs, and ADRs | `docs/research/logs/`, `docs/research/`, `docs/adr/` | all final claims | appendix-only tables |

paper/TABLE_MANIFEST.md

@@ -5,6 +5,6 @@
 | Table 1 | Study scope and research framing | `docs/research/01_research_program.md` | `C-FINAL-HEADLINE`, `C-FINAL-CLOSEOUT` | Included in main text |
 | Table 2 | Final knob families and signal tiers | `docs/research/02_tuning_theory_and_knob_space.md`, `docs/research/04_signal_and_profiling_plan.md` | `C-FINAL-SPLITK`, `C-FINAL-ROWS` | Included in main text |
 | Table 3 | Workload matrix summary | `docs/research/05_workload_matrix_and_case_studies.md` | `C-FINAL-H2`, `C-FINAL-H3` | Included in main text |
-| Table 4 | Final hypothesis and claim summary | `docs/research/11_final_claim_inventory.md`, `artifacts/analysis/final_paper_20260330/final_claim_table.csv` | all final claims | Included in main text |
+| Table 4 | Final hypothesis and claim summary | `docs/research/11_final_claim_inventory.md`, `docs/research/08_evidence_registry.md`, `docs/research/logs/2026-03-30_r6_final_synthesis_and_evidence_lock.md` | all final claims | Included in main text |
 | Appendix Table A1 | Round-by-round chronology | dated logs and `docs/research/07_experiment_campaign_plan.md` | provenance only | Appendix |
-| Appendix Table A2 | Canonical artifact map | `artifacts/analysis/final_paper_20260330/canonical_artifact_map.csv` | provenance only | Appendix |
+| Appendix Table A2 | Canonical artifact map | `docs/research/08_evidence_registry.md`, `docs/research/11_final_claim_inventory.md`, `docs/adr/ADR-001-single-host-single-gpu.md`, dated logs under `docs/research/logs/` | provenance only | Appendix |