merge: phase 14 — bench harness scoped/unscoped pass + v0.3.0a4

Wave 1 (14-A): LongMemEval haystack ingestion + isolated bench collection + v0.1.5 baseline re-capture
Wave 2 (14-B): dual-pass scoped runner at runner.py:428 + sibling-key envelope in report.py
Wave 2 (14-C): bundled scoped-smoke fixture + suite_loader dispatch
Wave 3 (14-D): ADR-0001 + CHANGELOG v0.3.0a4 + llms.txt + READMEs ×5 + version bump

Verifier: 677 passed / 4 skipped, ruff clean, uv build + twine clean.
Outstanding: GitHub-render checkpoint (D5) + tag/publish v0.3.0a4.

Author: dzmitrys-dev

CHANGELOG.md

@@ -2,6 +2,78 @@
 
 All notable changes to `supamem` will be documented in this file.
 
+## [0.3.0a4] — 2026-05-04 — Bench harness where-filter pass (Phase 14)
+
+### Added
+
+- **Scoped/unscoped bench passes.** `supamem eval --suite longmemeval_s`
+  now emits BOTH an unscoped and a scoped retrieval pass per question at
+  the single `runner.py:428` call site (`_run_longmemeval` per-record
+  loop). The scoped pass derives a per-question `where` filter from
+  LongMemEval haystack session ids (`{"session_id": [list]}`),
+  exercising Phase 7 / 9 / 11 / 14 indexer-side filter payloads end-to-end.
+  Smoke vs full continues to be gated by the existing `smoke_ids` filter
+  inside the same loop — no second physical call site.
+- **Bench-only LongMemEval ingestion.** New module
+  `supamem.eval.longmemeval_ingest` builds an isolated
+  `supamem_eval_longmemeval_s` collection, attaches `payload.session_id`
+  to each haystack chunk, and creates a `session_id` keyword payload
+  index at first ingestion (idempotent). Production indexer paths
+  (markdown, transcript) are unchanged. The `session_id` payload field
+  is **bench-only** — `supamem index` does NOT set it.
+- **Bundled smoke fixture.** New static fixture at
+  `src/supamem/eval/datasets/longmemeval_scoped_smoke.json` (≤5 questions,
+  ≤200 KB, self-contained — does not trigger the ~3 GB lazy fetch). New
+  suite name `longmemeval_scoped_smoke` for the CI fast-path; `suite_loader`
+  dispatches to the bundled fixture for that suite.
+- **ADR-0001** — `docs/adr/0001-scoped-only-bench-gate.md` records the
+  methodology, the v0.1.5 corpus mismatch disclosure (D-GATE-05), and
+  the strict isolation from FUTURE-24 (rerank composition rework) per
+  D-FUT24-01..03. New `docs/adr/` directory established with a
+  convention note (`docs/adr/README.md`).
+
+### Changed
+
+- **Result JSON shape.** `scores` and `by_axis` now carry `unscoped` +
+  `scoped` sibling sub-dicts. `_compute_main_score` for the
+  `longmemeval_s` suite reads `scores.scoped.tokens_per_correct_answer`
+  for the Phase 13 gate decision. Unscoped is reported in the same
+  envelope for transparency only — it never gates. Legacy callers
+  (goldens etc.) continue to see the flat shape (sibling-key envelope
+  contract pinned by `tests/test_build_report.py`).
+- **Gate decision is scoped-only.** The Phase 13 publication gate
+  (`baseline_delta.tokens_per_correct_answer ≤ -0.30`) now reads
+  `scores.scoped.tokens_per_correct_answer` against v0.1.5. Unscoped
+  numbers ship in the same envelope but never gate. See ADR-0001.
+
+### Migration
+
+- **v0.1.5 baseline re-captured.** `eval/baselines/v0.1.5.json` carries
+  both `unscoped` and `scoped` sibling keys plus a legacy mirror at
+  top-level for migration safety. The original devdocs-collection
+  number (`1374.59`) is preserved as `legacy_devdocs_unscoped_tpca` but
+  does NOT gate; v0.1.5 was re-captured against the new haystack
+  collection. **Absolute pre-Phase-14 numbers are not directly
+  comparable to post-Phase-14 numbers — the corpus changed.** See
+  ADR-0001 for the disclosure.
+
+### Cross-references
+
+- **FUTURE-24** (rerank composition rework) — Phase 14's scoped pass
+  runs with rerank-OFF so the measured scoped-vs-unscoped delta
+  attributes cleanly to scoping. FUTURE-24 is a SIBLING unblocker
+  tracked separately. Public claims about scoping gains do NOT
+  extrapolate to assume FUTURE-24 will further close the gap (D-FUT24-03).
+
+### Locks preserved
+
+- `runner.py:157` (`_run_goldens_legacy`, v0.1.x regression infra) is
+  **byte-identical** (D-VEND-04 lock). Plan B touched only
+  `runner.py:428`.
+- `retrieval/filters.py` is **byte-identical**. `session_id` flows
+  through Phase 11's existing pass-through path (key-name =
+  payload-key-name); not a magic key. Zero new branches.
+
 ## [0.3.0a3] — 2026-05-03 — Filtered retrieval backend (FILT-01) + anti-identity-tier lock (FILT-02)
 
 ### Added

README.es.md

@@ -1,6 +1,6 @@
 **Idiomas:** [English](README.md) · [简体中文](README.zh-CN.md) · [Español](README.es.md) · [日本語](README.ja.md) · [Русский](README.ru.md)
 
-<!-- synced-with: README.md @ b5a3522 -->
+<!-- synced-with: README.md @ 612a256 -->
 
 > Esta traducción fue generada con asistencia de IA. Las correcciones de hablantes nativos son bienvenidas vía PR.
 
@@ -343,7 +343,7 @@ y el recordatorio para que descubras este flujo de manera natural.
 | `supamem stats` | Contadores Welford schema-v2 desde `.supamem/state/` |
 | `supamem live` | 👀 Dashboard en vivo siguiendo el audit JSONL — pipe-safe (JSONL plano cuando no hay TTY); maneja rotación, redimensionado, Ctrl-C |
 | `supamem migrate` | Migración brownfield desde una colección `dev_memory` preexistente |
-| `supamem eval` | Correr el arnés de bench. `--suite goldens` (por defecto, corpus dorado de 33 consultas para regresión) o `--suite longmemeval_s` (descarga perezosa de LongMemEval_S, ~3 GB en la primera ejecución; el camino rápido de CI es un subconjunto de 10 preguntas estratificado por eje, las ~500 preguntas completas requieren `--full`). Emite un envelope JSON estilo MTEB a `~/.supamem/eval/<utc-iso>.json`. El juez por defecto es heurístico (offline); pasa `--judge ollama:<model>` para un juez Ollama local — los endpoints SaaS son rechazados (D-07). Extra opcional: `pip install supamem[eval]` para la tríada RAGAS (v0.3.0a2+). Modo legado `--regress` preservado. |
+| `supamem eval` | Correr el arnés de bench. `--suite goldens` (por defecto, corpus dorado de 33 consultas para regresión) o `--suite longmemeval_s` (descarga perezosa de LongMemEval_S, ~3 GB en la primera ejecución; el camino rápido de CI es un subconjunto de 10 preguntas estratificado por eje, las ~500 preguntas completas requieren `--full`). v0.3.0a4+: emite una pasada scoped + unscoped por pregunta; el gate de publicación es **scoped-only** ([ADR-0001](docs/adr/0001-scoped-only-bench-gate.md)). Nuevo `--suite longmemeval_scoped_smoke` empaquetado (≤5 preguntas, sin descarga perezosa) para CI. Emite un envelope JSON estilo MTEB a `~/.supamem/eval/<utc-iso>.json`. El juez por defecto es heurístico (offline); pasa `--judge ollama:<model>` para un juez Ollama local — los endpoints SaaS son rechazados (D-07). Extra opcional: `pip install supamem[eval]` para la tríada RAGAS (v0.3.0a2+). Modo legado `--regress` preservado. |
 | `supamem uninstall --client <name>` | Revertir `supamem install` limpiamente |
 | `supamem unpatch-agents` | 🔄 Revertir los parches de alcance de subagentes (v0.2.5+). Restaura los archivos de agentes a su forma anterior al parche según el manifiesto en `~/.cache/supamem/agent_patches.json`. Omite con advertencia los archivos que hayas editado desde entonces. Córrelo ANTES de `pip uninstall supamem` para una desinstalación limpia. |
 
@@ -618,6 +618,13 @@ Semántica:
 Múltiples keys de `where` se AND-ean; los valores en lista dentro de una key se OR-ean
 (`MatchAny`).
 
+| Key | Semántica |
+|-----|-----------|
+| `room` | Phase 7 — facet del clasificador de coding-path (`backend`, `frontend`, `tests`, ...). String o lista. Lo escribe `supamem index` por chunk. |
+| `path_prefix` | Phase 11 — match exacto left-anchored por segmentos de path contra `payload.path_prefixes`. String o lista. Lo escribe `supamem index` por chunk. |
+| `valid_to` | Phase 9 — solo acepta `"now"` como alias no-op de la cláusula temporal always-on. Cualquier otro valor lanza `ValueError`. |
+| `session_id` | **Solo bench** — lo escribe la ingestión LongMemEval (`supamem.eval.longmemeval_ingest`); es key pass-through. **`supamem index` NO lo escribe.** Lo usa la pasada scoped del bench Phase 14 contra la colección dedicada `supamem_eval_longmemeval_s`. Ver [ADR-0001](docs/adr/0001-scoped-only-bench-gate.md). |
+
 ### Migración
 
 Los chunks legados (indexados antes de v0.3.0a3) no tienen `path_prefixes`. El primer
@@ -633,6 +640,48 @@ voltea el exit code del doctor.
 
 ---
 
+## 📊 Benchmarks (v0.3.0a4+)
+
+**Cambio metodológico.** `supamem eval --suite longmemeval_s` emite tanto una
+pasada **unscoped** como una **scoped** por pregunta. La pasada scoped usa
+un `where` filter por pregunta derivado de los session ids del haystack de
+LongMemEval (`{"session_id": [...]}`), ejercitando los payloads de filtro
+del lado del indexer (`room`, `path_prefix`, `valid_to`, `session_id`)
+agregados a lo largo de las Phases 7 / 9 / 11 / 14. La decisión del gate
+publicado (delta de `tokens_per_correct_answer` vs el baseline v0.1.5) lee
+la pasada **scoped**; unscoped se reporta en el mismo envelope para
+transparencia y nunca gating. Ver [ADR-0001](docs/adr/0001-scoped-only-bench-gate.md)
+para el racional completo.
+
+**Caveat de reproducibilidad.** Los números scoped pueden no reproducirse
+en invocaciones unscoped por defecto de `dual_memory_search` /
+`qdrant_find`. Los usuarios que quieran números comparables deben pasar un
+`where={...}` explícito contra una colección cuyos chunks lleven el payload
+correspondiente — esta es una disclosure metodológica, no un defecto.
+
+**Corpus baseline.** El baseline v0.1.5 fue **re-capturado** contra una
+colección de bench dedicada (`supamem_eval_longmemeval_s`). Los números
+absolutos pre-Phase-14 no son directamente comparables a los números
+post-Phase-14 — el corpus cambió. El número original de la devdocs
+collection se preserva como `legacy_devdocs_unscoped_tpca` en
+`eval/baselines/v0.1.5.json` para referencia histórica pero **NO** entra
+al gate.
+
+**FUTURE-24 (rerank composition rework)** es un sibling unblocker
+trackeado por separado. La pasada scoped de Phase 14 corre con rerank-OFF
+para que el delta scoped-vs-unscoped medido atribuya limpiamente al
+scoping. Las claims públicas sobre las ganancias de scoping **no** se
+extrapolan a "y una vez que el rerank composition también se arregle, el
+gate cerrará por X% más".
+
+**Smoke fixture.** Un fixture empaquetado en
+`src/supamem/eval/datasets/longmemeval_scoped_smoke.json` (≤5 preguntas,
+≤200 KB, self-contained) está expuesto como el nuevo suite
+`longmemeval_scoped_smoke` — corre en CI sin disparar la descarga
+perezosa de ~3 GB.
+
+---
+
 ## 🚫 Lo que supamem **NO** hace
 
 `supamem` **NO** auto-inyecta contexto de identity / wake-up / prelude en las llamadas

README.ja.md

@@ -1,6 +1,6 @@
 **言語:** [English](README.md) · [简体中文](README.zh-CN.md) · [Español](README.es.md) · [日本語](README.ja.md) · [Русский](README.ru.md)
 
-<!-- synced-with: README.md @ b5a3522 -->
+<!-- synced-with: README.md @ 612a256 -->
 
 > この翻訳は AI 支援によるものです。ネイティブスピーカーによる修正 PR を歓迎します。
 
@@ -335,7 +335,7 @@ pip uninstall supamem
 | `supamem stats` | `.supamem/state/` からの Welford schema-v2 利用カウンタ |
 | `supamem live` | 👀 audit JSONL を追跡するライブダッシュボード — パイプセーフ(非 TTY 時はプレーン JSONL);ローテーション、リサイズ、Ctrl-C を処理 |
 | `supamem migrate` | 既存 `dev_memory` コレクションからのブラウンフィールド移行 |
-| `supamem eval` | bench ハーネスを実行。`--suite goldens`(デフォルト、内蔵 33 クエリのリグレッション正解コーパス)または `--suite longmemeval_s`(初回実行時に LongMemEval_S を遅延フェッチ、~3 GB;CI 高速パスは軸別層化された 10 問サブセット、完全な ~500 問は `--full` でゲート)。MTEB 形式の JSON envelope を `~/.supamem/eval/<utc-iso>.json` に出力。デフォルトジャッジはオフラインのヒューリスティック;ローカル Ollama ジャッジは `--judge ollama:<model>` で指定 — SaaS エンドポイントは拒否されます(D-07)。オプション extra: `pip install supamem[eval]` で RAGAS トライアド有効(v0.3.0a2+)。レガシー `--regress` モードは温存。 |
+| `supamem eval` | bench ハーネスを実行。`--suite goldens`(デフォルト、内蔵 33 クエリのリグレッション正解コーパス)または `--suite longmemeval_s`(初回実行時に LongMemEval_S を遅延フェッチ、~3 GB;CI 高速パスは軸別層化された 10 問サブセット、完全な ~500 問は `--full` でゲート)。v0.3.0a4+:質問ごとに scoped と unscoped の 2 パスを発行し、公開 gate は **scoped 専用**([ADR-0001](docs/adr/0001-scoped-only-bench-gate.md))。CI 用に新たな内蔵 `--suite longmemeval_scoped_smoke`(≤5 問、遅延フェッチなし)を追加。MTEB 形式の JSON envelope を `~/.supamem/eval/<utc-iso>.json` に出力。デフォルトジャッジはオフラインのヒューリスティック;ローカル Ollama ジャッジは `--judge ollama:<model>` で指定 — SaaS エンドポイントは拒否されます(D-07)。オプション extra: `pip install supamem[eval]` で RAGAS トライアド有効(v0.3.0a2+)。レガシー `--regress` モードは温存。 |
 | `supamem uninstall --client <name>` | `supamem install` をクリーンに反転 |
 | `supamem unpatch-agents` | 🔄 サブエージェント到達性パッチを反転(v0.2.5+)。`~/.cache/supamem/agent_patches.json` のマニフェストに従って agent ファイルをパッチ前の形に復元。あなたが編集済みのファイルは警告付きでスキップ。クリーンなアンインストールのため `pip uninstall supamem` の前に実行してください。 |
 
@@ -603,6 +603,13 @@ dual_memory_search(query="session", where={"valid_to": "now"})
 
 `where` の複数キーは AND、同一キー内のリスト値は OR(`MatchAny`)です。
 
+| キー | 意味 |
+|------|------|
+| `room` | Phase 7 — coding-path 分類器のファセット(`backend`、`frontend`、`tests` など)。文字列またはリスト。`supamem index` が chunk 単位で書き込みます。 |
+| `path_prefix` | Phase 11 — `payload.path_prefixes` に対する left-anchored の path-segment 完全一致。文字列またはリスト。`supamem index` が chunk 単位で書き込みます。 |
+| `valid_to` | Phase 9 — 常時オンの temporal 句のエイリアスとして `"now"` のみ受理。それ以外の値は `ValueError`。 |
+| `session_id` | **bench 専用** — LongMemEval ingestion(`supamem.eval.longmemeval_ingest`)が書き込む pass-through キー。**`supamem index` は書き込みません。** Phase 14 の scoped bench パスが専用コレクション `supamem_eval_longmemeval_s` に対して使用します。詳細は [ADR-0001](docs/adr/0001-scoped-only-bench-gate.md) を参照。 |
+
 ### マイグレーション
 
 レガシー chunk(v0.3.0a3 より前にインデックスされたもの)は `path_prefixes` を持ちません。
@@ -618,6 +625,44 @@ exit code を変えることはありません。
 
 ---
 
+## 📊 Benchmarks(v0.3.0a4+)
+
+**方法論の変更。** `supamem eval --suite longmemeval_s` は質問ごとに
+**unscoped** と **scoped** の両方の検索パスを発行します。scoped パスは
+LongMemEval の haystack session id から導出した質問ごとの `where` フィルタ
+(`{"session_id": [...]}`)を使用し、Phase 7 / 9 / 11 / 14 で追加された
+indexer 側のフィルタ payload(`room`、`path_prefix`、`valid_to`、
+`session_id`)をエンドツーエンドで動かします。公開 gate の判定
+(`tokens_per_correct_answer` の v0.1.5 baseline に対する delta)は **scoped**
+パスを読み、unscoped は同じ envelope に透明性のために載りますが gate には
+入りません。詳細は [ADR-0001](docs/adr/0001-scoped-only-bench-gate.md) を参照。
+
+**再現性に関する注意。** scoped の数値は `dual_memory_search` /
+`qdrant_find` のデフォルト unscoped 呼び出しでは再現しない可能性があります。
+比較可能な数値が欲しいユーザーは、対応する payload を持つ chunk を含む
+コレクションに対して明示的に `where={...}` を渡す必要があります —— これは
+方法論の開示であり欠陥ではありません。
+
+**Baseline コーパス。** v0.1.5 の baseline は専用 bench コレクション
+(`supamem_eval_longmemeval_s`)上で **再キャプチャ**されました。Phase 14
+以前の絶対値は Phase 14 以降の値と直接比較できません —— コーパスが変わった
+ためです。元の devdocs collection 由来の数値は
+`eval/baselines/v0.1.5.json` に `legacy_devdocs_unscoped_tpca` として歴史
+参照のために保存されますが、**gate には入りません**。
+
+**FUTURE-24(rerank composition rework)** は別途追跡される姉妹アンブロッカー
+です。Phase 14 の scoped パスは rerank-OFF で走るため、計測される
+scoped と unscoped の差分は scoping にきれいに帰属します。scoping の
+ゲインに関する公開クレームは「rerank composition も直れば gate がさらに
+X% 縮まる」とは **外挿しません**。
+
+**Smoke fixture。** 内蔵された静的 fixture
+`src/supamem/eval/datasets/longmemeval_scoped_smoke.json`(≤5 問、≤200 KB、
+self-contained)が新スイート名 `longmemeval_scoped_smoke` として公開され、
+~3 GB の遅延フェッチをトリガせずに CI で実行できます。
+
+---
+
 ## 🚫 supamem が **やらないこと**
 
 `supamem` は **エージェント呼び出しに identity / wake-up / prelude コンテキストを自動