[agent-kb] Fveritas: the problem factory — a harness that generates, gates, and solves its own research problems

.gitignore

@@ -58,6 +58,7 @@ scripts/_*
 /results/
 /tmp/
 /.external/
+.venv/
 .venv-tenpy/
 .pytest_cache/
 .coverage

.knowledge/models/ref.bib

@@ -239,3 +239,23 @@ @Article{daley_2014_quantum
  volume = {63},
  year = {2014}
 }
+
+@article{Schulenburg2002,
+  author  = {Schulenburg, J. and Honecker, A. and Schnack, J. and Richter, J. and Schmidt, H.-J.},
+  title   = {Macroscopic magnetization jumps due to independent magnons in frustrated quantum spin lattices},
+  journal = {Phys. Rev. Lett.},
+  volume  = {88},
+  pages   = {167207},
+  year    = {2002},
+  doi     = {10.1103/PhysRevLett.88.167207}
+}
+
+@article{Derzhko2015,
+  author  = {Derzhko, O. and Richter, J. and Maksymenko, M.},
+  title   = {Strongly correlated flat-band systems: rigorous and perturbative approaches},
+  journal = {Int. J. Mod. Phys. B},
+  volume  = {29},
+  pages   = {1530007},
+  year    = {2015},
+  doi     = {10.1142/S0217979215300078}
+}

.knowledge/models/sawtooth-chain/MODEL.md

@@ -0,0 +1,79 @@
+# Sawtooth chain
+
+Solve the spin-1/2 sawtooth (delta) chain — a frustrated chain of corner-sharing triangles that is *exactly* solvable at high field through localized-magnon physics at the flat-band point `J2 = 2 J1`: magnetization jump, `m = M_sat/2` plateau, and residual entropy.
+Exact solution: see `.knowledge/solvable/sawtooth-localized-magnon/` (oracle card).
+
+## Physics card
+
+### Hamiltonian
+
+$$ H = \sum_i \left[\, J_1\,\mathbf{S}_{A_i}\!\cdot\!\mathbf{S}_{A_{i+1}} + J_2\,(\mathbf{S}_{A_i}\!\cdot\!\mathbf{S}_{B_i} + \mathbf{S}_{B_i}\!\cdot\!\mathbf{S}_{A_{i+1}})\,\right] - h \sum_i S^z_i $$
+
+Conventions: spin-1/2 `S`-operators (`d=2`); `N = 2N_c` sites, base `A_i` = site `2i`, apex `B_i` = site `2i+1` (0-based), PBC. `J1` is the base-chain exchange, `J2` the apex–base exchange; both antiferromagnetic (`>0`), `J1 = 1` sets the unit. Control parameter: the ratio `J2/J1` (flat-band point at `2`, Monti–Sütő point at `1` — distinct, do not conflate). See `.knowledge/conventions.md`.
+
+### Properties (A1–D16)
+
+| Axis | Value | Note |
+|---|---|---|
+| A1 dimension & geometry | 1D, corner-sharing triangles (base chain + apex sites), `Z = 4` | The triangle geometry is what makes magnons localizable. |
+| A2 boundary conditions | PBC (ED default) | Localized-magnon counting assumes the ring. |
+| A3 statistics & local dim | spin-1/2; `d = 2` | — |
+| A4 interaction range | short-range (base NN `J1`, apex–base `J2`) | Local. |
+| B5 entanglement scaling | localized-magnon states: product-like at the flat-band point | Flat-band eigenstates are single-cell objects. |
+| B6 spectral gap | one-magnon band exactly flat at `J2 = 2 J1` (zero dispersion) | Flatness is exact, not small. |
+| B7 ground-state order | `h = 0`: spin-liquid-like, no simple order; `h = h_sat`: localized-magnon crystal (`m = M_sat/2` plateau) | The plateau state is an exact magnon crystal at the flat-band point. |
+| B8 frustration | strong geometric frustration (triangles) | Frustration enables destructive interference → flat band. |
+| C9 global symmetry | SU(2) (total spin); field breaks to U(1) | `S^z_tot` sectors are the workhorse basis. |
+| C10 spatial symmetry | translation (one cell), reflection | Localized magnons break translation spontaneously at the plateau. |
+| C11 integrability | not integrable, but **exact eigenstates at `J2 = 2 J1`** (localized magnons) and an exact two-fold GS at `J2 = J1` (Monti–Sütő) | Tier-C solvability: special points only — see solvable card. |
+| C12 sign problem | sign-ful (frustration) → QMC blocked; ED/DMRG carry it | Frustration turns on the sign problem. |
+| D13 regime | ground state + magnetization process in a field; finite-T (magnetocaloric effect) | The MCE near `h_sat` is the materials connection. |
+| D14 filling / doping | N/A (spin model; `m/m_sat` is the field-tuned analog) | — |
+| D15 disorder | clean by default | — |
+| D16 hermiticity | Hermitian / closed | — |
+
+### Phases & order parameters
+
+- `m = M_sat/2` plateau (localized-magnon crystal): at `J2 = 2 J1` an exact product of independent cell magnons; width `W(J2/J1)` shrinks linearly as the flat band is detuned (reconnaissance ED, N≤16).
+- Saturation (`m = M_sat`): reached via a **macroscopic jump** `ΔM = M_sat/2` at `h_sat = 4 J1` exactly at the flat-band point; the jump smears into a staircase for `J2 ≠ 2 J1` with width Γ set by the detuned one-magnon bandwidth.
+- Zero-field GS: featureless spin-liquid-like; at `J2 = J1` the exact Monti–Sütő two-fold valence-bond state.
+
+### Canonical observables
+
+- Ground-state energy per sector `E(S^z_tot)`; magnetization curve `m(h)` with plateau width `W` and jump height `ΔM`.
+- Ground-state degeneracy at `h_sat` (exact integer, Lucas numbers); residual entropy `S/N`.
+- One-magnon dispersion (flatness); finite-T isothermal entropy peak and magnetocaloric cooling rate near `h_sat`.
+
+### Recommended methods
+
+- Primary: **ED** in `S^z_tot` sectors — the exact anchors are sector-resolved, and N ≤ 20 covers all of them (see `skills/method-ed/SKILL.md`, `skills/using-xdiag/SKILL.md`).
+- Cross-check: the **solvable oracle** (`.knowledge/solvable/sawtooth-localized-magnon/`) — flat band, Lucas degeneracy, jump; DMRG for larger-N erosion curves; FTLM for the finite-T magnetocaloric axis.
+
+### Key reference
+
+[@Schulenburg2002] — Schulenburg–Honecker–Schnack–Richter–Schmidt, the foundational localized-magnon paper (flat-band condition, macroscopic jump, exact eigenstates). `bib stub — no PDF reachable (2026-07-28)`; review [@Derzhko2015].
+
+### Benchmarks
+
+- Flat-band one-magnon energy `ε = −4 J1` at `J2 = 2 J1` — exact; verified by ED + XDiag (Harness anchor, solvable card).
+- Saturation field `h_sat = 4 J1`; jump `ΔM = M_sat/2` — exact (Harness anchor).
+- Degeneracy at `h_sat` = Lucas(N_c) (`N=12 → 18`); `S/N = (1/2) ln φ ≈ 0.2406 k_B` — exact (Harness anchor).
+- Erosion reconnaissance (N=12–16 ED): `W(δ)` peaks at δ=0 and falls ~linearly; `ΔM` is full only at δ=0; `Γ(δ)` tracks the one-magnon bandwidth (Harness anchor, `tracks/agent-kb/solutions/problem-factory/briefs/sawtooth-erosion-001.md`).
+
+## How it is studied / Operational
+
+**Canonical defaults (Diagnose):** spin-1/2, AFM `J1 = 1`, ratio `J2/J1` from the prompt (default the flat-band point `2`), PBC, `S^z_tot` sectors enumerated from polarization (`n_up = N − k`, `k = 0…N/2`), target `m(h)` + the exact anchors. If only "sawtooth" is given, propose the anchor battery at `J2 = 2 J1` (flat band, jump, degeneracy, entropy) and a detuning sweep `δ = J2/J1 − 2` for the erosion curves.
+
+| Regime | Method | Card |
+|---|---|---|
+| Anchor battery (flat band, jump, Lucas degeneracy) | ED per `S^z_tot` sector, N ≤ 20 | `skills/method-ed/SKILL.md` |
+| Erosion curves `W(δ), Γ(δ)` at larger N | ED → DMRG | `skills/method-ed/SKILL.md`, `skills/method-mps/SKILL.md` |
+| Finite-T magnetocaloric effect | full-spectrum ED (N ≤ 20) / FTLM | `skills/method-ed/SKILL.md` |
+| Exact checks at any step | solvable oracle | `.knowledge/solvable/sawtooth-localized-magnon/` |
+
+Verification pointers:
+
+- The `h_sat` degeneracy is an **exact integer** (Lucas(N_c)) — off by one is a bug, not a discrepancy.
+- `J2/J1 = 1` (Monti–Sütő) and `2` (flat band) are different special points; conflating them is a known trap.
+- Convention trap: energies off by ~4× mean Pauli-vs-spin mix-up; a flat band at `−2 J1` means a `J2` bond was double-counted.
+- `S^z_tot` conservation always; at the flat-band point additionally verify the one-magnon band is flat to solver precision before trusting any detuning sweep.

.knowledge/models/transverse-field-ising/MODEL.md

@@ -59,6 +59,8 @@ Rendered: `./1012.0653_quantum-phase-transitions-in-transverse-field-spin-models
 
 - 1D chain QCP: `Γ_c/J = 1` exactly (self-dual / Jordan–Wigner); at criticality `c = 1/2`, `ν = 1`, `β = 1/8`. Ground-state energy density at `Γ = J = 1`: `E/N = −4/π ≈ −1.2732` (Pauli convention `H = −J Σ σ^z σ^z − Γ Σ σ^x`; from the free-fermion dispersion, consistent with this card's Verification note).
 - 2D square FM TFIM: critical field `(Γ/J)_c = 3.04438(2)`, 3D-Ising universality (Blöte & Deng, Phys. Rev. E 66, 066110 (2002)).
+- 2D triangular FM TFIM: `(Γ/J)_c = 4.76811(9)`; honeycomb: `2.13250(4)` (same reference, Table I). *Literal* — quoted verbatim in challenge issue #148, which reports their ratio 2.23592(6) at 2.4σ from √5; no post-2002 improvement found in a 203-citation sweep (2026-07-30). Still the SOTA pair.
+- Recon-scale ED crossings (Binder cumulant, PBC clusters N ≤ 18): triangular 4.342 ± 0.002, honeycomb 1.986 ± 0.062, square 2.870 — systematically ~5–7 % below the QMC values at these sizes, drifting upward with N. *Harness anchor* — `tracks/agent-kb/solutions/problem-factory/run_sqrt5.py` (2026-07-30), builder cross-checked against Jordan–Wigner chain + exact dimer/classical/strong-field limits (`tests/test_tfim2d.py`).
 
 ## Diagnose
 

.knowledge/solvable/INDEX.md

@@ -113,6 +113,7 @@ built `ORACLE.md` where available.
 | `aklt-honeycomb` | C | P | ✓ wave 3 | [ORACLE](./aklt-honeycomb/ORACLE.md) |
 | `majumdar-ghosh` | C | S | ✓ wave 3 | [ORACLE](./majumdar-ghosh/ORACLE.md) |
 | `shastry-sutherland-dimer` | C | S | ✓ wave 3 | [ORACLE](./shastry-sutherland-dimer/ORACLE.md) |
+| `sawtooth-localized-magnon` | C | S | ✓ wave 4 | [ORACLE](./sawtooth-localized-magnon/ORACLE.md) |
 | `rk-quantum-dimer` | C | S | ✓ wave 3 | [ORACLE](./rk-quantum-dimer/ORACLE.md) |
 | `motzkin-fredkin` | C | S | ✓ wave 3 | [ORACLE](./motzkin-fredkin/ORACLE.md) |
 | `eta-pairing-hubbard` | C | S | ✓ wave 3 | [ORACLE](./eta-pairing-hubbard/ORACLE.md) |

.knowledge/solvable/ref.bib

@@ -1086,3 +1086,43 @@ @article{Fisher1966
   year    = {1966},
   doi     = {10.1063/1.1704825}
 }
+
+@article{Schulenburg2002,
+  author  = {Schulenburg, J. and Honecker, A. and Schnack, J. and Richter, J. and Schmidt, H.-J.},
+  title   = {Macroscopic magnetization jumps due to independent magnons in frustrated quantum spin lattices},
+  journal = {Phys. Rev. Lett.},
+  volume  = {88},
+  pages   = {167207},
+  year    = {2002},
+  doi     = {10.1103/PhysRevLett.88.167207}
+}
+
+@article{MontiSuto1991,
+  author  = {Monti, F. and Sütő, A.},
+  title   = {Exact ground states of a class of frustrated quantum spin models},
+  journal = {Phys. Lett. A},
+  volume  = {156},
+  pages   = {197--199},
+  year    = {1991},
+  doi     = {10.1016/0375-9601(91)90937-4}
+}
+
+@article{ZhitomirskyHonecker2004,
+  author  = {Zhitomirsky, M. E. and Honecker, A.},
+  title   = {Magnetocaloric effect in one-dimensional antiferromagnets},
+  journal = {J. Stat. Mech.},
+  volume  = {2004},
+  pages   = {P07012},
+  year    = {2004},
+  doi     = {10.1088/1742-5468/2004/07/P07012}
+}
+
+@article{Derzhko2015,
+  author  = {Derzhko, O. and Richter, J. and Maksymenko, M.},
+  title   = {Strongly correlated flat-band systems: rigorous and perturbative approaches},
+  journal = {Int. J. Mod. Phys. B},
+  volume  = {29},
+  pages   = {1530007},
+  year    = {2015},
+  doi     = {10.1142/S0217979215300078}
+}

.knowledge/solvable/sawtooth-localized-magnon/ORACLE.md

@@ -0,0 +1,53 @@
+# Sawtooth-chain localized magnons — exact-solution oracle
+
+Technique: T5 (frustration-free / exact eigenstates) · Tier: C (exact eigenstates and degeneracies at special points) · Script: S
+
+## Hamiltonian & conventions
+
+$$ H = \sum_i \left[\, J_1\,\mathbf{S}_{A_i}\!\cdot\!\mathbf{S}_{A_{i+1}} + J_2\,(\mathbf{S}_{A_i}\!\cdot\!\mathbf{S}_{B_i} + \mathbf{S}_{B_i}\!\cdot\!\mathbf{S}_{A_{i+1}})\,\right] - h \sum_i S^z_i $$
+
+Conventions: spin-½ `S`-operators (`d = 2`); sawtooth (delta) chain with `N = 2N_c` sites, base `A_i` = site `2i`, apex `B_i` = site `2i+1` (0-based), PBC. `J1` couples base–base along the chain, `J2` couples apex–base (two bonds per apex). Both AFM (`> 0`), `J1 = 1` sets the unit. See `.knowledge/conventions.md`.
+
+Physics card: `.knowledge/models/sawtooth-chain/MODEL.md` (same `J1`/`J2` convention).
+
+**Two distinct special points — do not conflate** (flagged trap in QuantumBFS/quantum.harness#112): the **flat-band point** `J2 = 2 J1` (localized magnons, high-field exactness) and the **Monti–Sütő point** `J2 = J1, h = 0` (exact two-fold valence-bond ground state).
+
+## Solvability statement
+
+T5: at `J2 = 2 J1` the lowest one-magnon band is **exactly flat** (destructive interference localizes a magnon on a single cell), so the many-magnon problem at the saturation field reduces to **independent localized particles with a hard-dimer exclusion** (no two magnons on adjacent cells). Exact: the flat-band energy, the saturation field, the magnetization jump, the full ground-state degeneracy at `h_sat` (hard-dimer/Lucas count), and the residual entropy; at `J2 = J1`, the two-fold ground state. **Not exact:** the spectrum away from these points, the detuned (`J2 ≠ 2 J1`) erosion curves, excitations, and finite-T thermodynamics — all numerical (see `tracks/agent-kb/solutions/problem-factory/briefs/sawtooth-erosion-001.md` for first erosion curves).
+
+## Exact results
+
+- Flat band: one-magnon energy `ε = −2 J2 = −4 J1` at `J2 = 2 J1`, dispersionless [@Schulenburg2002]
+- Saturation field `h_sat = 2 J2 = 4 J1` [@Schulenburg2002]
+- Magnetization jump at `h_sat`: `ΔM = M_sat/2` (macroscopic, from `N/4` zero-cost magnons) [@Schulenburg2002]
+- Ground-state degeneracy at `h_sat` = number of hard-dimer coverings of the `N_c`-cell ring = **Lucas(`N_c`)**; `N = 12` (`N_c = 6`) → `18` [@ZhitomirskyHonecker2004]
+- Residual entropy `S/N = (1/2) ln φ ≈ 0.2406 k_B` (φ golden ratio) [@ZhitomirskyHonecker2004]
+- Monti–Sütő point `J2 = J1, h = 0`: exact two-fold valence-bond ground state [@MontiSuto1991]
+
+## Oracle script
+
+`python oracle.py --N 12 --j2 2.0 --h 4.0` → prints `one_magnon_band_min/max`, `e_ground`, `gs_degeneracy`, `entropy_per_site`. Importable: `compute(N=12, j2=2.0, j1=1.0, h=4.0)`; builder `sawtooth_hamiltonian(N, j2, j1, h, n_up)`. `python oracle.py self-test` runs the anchors.
+
+Self-test anchors (all N=12): (1) one-magnon band flat, `min = max = −4` to 1e-10; (2) `e_ground` at `h_sat` equals the polarized-state energy `−16.5`; (3) `gs_degeneracy = 18` exactly; (4) `S/N = 0.2409 ≈ 0.2406`; (5) sector ground energies flat for `k ≤ N/4` and strictly rising above (hard-dimer constraint — the jump plateau); (6) Monti–Sütő doublet: `E₂−E₁ < 1e-10`, `E₃−E₁ > 1e-3`.
+
+## Benchmarks
+
+| Quantity | Params | Exact value | Source |
+|---|---|---|---|
+| `one_magnon_band_min=max` | `J2 = 2`, `h = 0` | `−4.0` | [@Schulenburg2002]; ED this card (dense, N=12) + XDiag cross-check |
+| `e_ground` | `J2 = 2`, `h = 4`, N=12 | `−16.5` | Analytic (polarized energy); ED + XDiag |
+| `gs_degeneracy` | `J2 = 2`, `h = 4`, N=12 | `18` (= Lucas(6)) | [@ZhitomirskyHonecker2004]; ED + XDiag |
+| `entropy_per_site` | N=12 | `0.2409` (`→ 0.2406` as N→∞) | [@ZhitomirskyHonecker2004]; ED |
+| `E₂−E₁` | `J2 = 1`, `h = 0`, N=12 | `0` (twofold) | [@MontiSuto1991]; ED + XDiag |
+
+Cross-check: `tracks/agent-kb/solutions/problem-factory/scripts/xdiag_crosscheck.jl` (XDiag 0.5.0, julia-env) reproduces all anchors to ≤ 1e-8 — **Harness anchor**.
+
+## Verification recipes
+
+- To check any ED/DMRG sawtooth run at `J2 = 2 J1`: the one-magnon sector must be flat at `−4 J1` (spread < 1e-8), and the `h_sat` ground-state degeneracy must be an **exact integer** (Lucas(N_c)) — off by one is a bug, not a discrepancy.
+- Convention trap: an energy per site off by a factor ~4 means Pauli-vs-spin mix-up; a "flat band" at `−2 J1` means the apex coupling was doubled by mistake (counting both `J2` bonds twice).
+
+## Key reference
+
+[@Schulenburg2002] — Schulenburg, Honecker, Schnack, Richter, Schmidt, PRL 88, 167207 (2002): the canonical localized-magnon paper (flat-band condition, jump, exact eigenstates). `bib stub — no PDF reachable (2026-07-28)`. Review: [@Derzhko2015].