feat(tooling): add locomo single-knob auto-stop gate

README.md

@@ -195,12 +195,14 @@ tools/locomo/run-regression-gate.sh 5
 tools/locomo/run-category-gate.sh 5
 tools/locomo/run-full-gate.sh 5
 tools/locomo/refresh-failure-samples.sh 5 80
+./.venv/bin/python tools/locomo/evaluate-single-knob.py
 ```
 
 - Scripts write artifacts to `/tmp` by default (or `BASE_DIR` when provided).
 - `run-regression-gate.sh` default threshold is `hit@5 >= 0.55` (second arg can override).
 - `run-category-gate.sh` also checks default category floors for `multi-hop` and `open-domain`.
 - `run-full-gate.sh` runs baseline threshold checks, drift checks, and the required 4-command matrix in one command.
+- `evaluate-single-knob.py` enforces an auto-stop rule: only recommend a change when both `overall` and `multi-hop` improve; otherwise output `NO-OP`.
 - CI gate workflow `.github/workflows/locomo-full-gate.yml` runs `REBUILD_PYTHON=0 tools/locomo/run-full-gate.sh 5` on PRs and pushes to `main` (plus manual dispatch), and uploads gate artifacts.
 - If LoCoMo scores unexpectedly remain old, rebuild local Python binding:
   `./.venv/bin/python -m pip install -e python`

docs/superpowers/plans/2026-03-19-v2-r14-locomo-single-knob-gate-implementation-plan.md

@@ -0,0 +1,49 @@
+# V2-R14 LoCoMo Single-Knob Gate Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a minimal evaluator script that enforces NO-OP unless `overall` and `multi-hop` both improve.
+
+**Architecture:** Keep retrieval engine untouched; add one tooling script and docs updates only.
+
+**Tech Stack:** Python script in `tools/locomo` + markdown docs.
+
+---
+
+### Task 1: Add Evaluator Script
+
+**Files:**
+- Create: `tools/locomo/evaluate-single-knob.py`
+
+- [ ] Implement baseline and candidate evaluation for K=5 LoCoMo retrieval.
+- [ ] Hardcode pass rule (`overall` and `multi-hop` both improve).
+- [ ] Emit clear JSON decision payload (`APPLY` or `NO-OP`).
+
+### Task 2: Update Docs
+
+**Files:**
+- Modify: `tools/locomo/README.md`
+- Modify: `README.md`
+
+- [ ] Document command usage.
+- [ ] Document auto-stop decision rule.
+
+### Task 3: Verification
+
+**Files:**
+- No source edits
+
+- [ ] `./.venv/bin/python tools/locomo/evaluate-single-knob.py`
+- [ ] `cargo test --workspace`
+- [ ] `./.venv/bin/pytest python/tests -q`
+- [ ] `corepack pnpm --dir packages/node test`
+- [ ] `corepack pnpm --dir packages/mcp test`
+- [ ] `REBUILD_PYTHON=0 tools/locomo/run-full-gate.sh 5`
+
+### Task 4: Finish
+
+**Files:**
+- Create: `docs/superpowers/releases/2026-03-19-v2-r14-locomo-single-knob-gate-results.md`
+
+- [ ] Record decision output and verification evidence.
+- [ ] Commit and merge.

docs/superpowers/plans/2026-03-19-v2-r15-locomo-closure-implementation-plan.md

@@ -0,0 +1,37 @@
+# V2-R15 LoCoMo Closure Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Finalize LoCoMo V2 with evidence-backed closure and a stable tag.
+
+**Architecture:** Docs and release-management only; no retrieval code changes.
+
+**Tech Stack:** markdown docs + git tag + existing validation commands.
+
+---
+
+### Task 1: Closure Documentation
+
+**Files:**
+- Create: `docs/superpowers/releases/2026-03-19-v2-r15-locomo-closure-results.md`
+
+- [ ] Record closure criteria and evidence references.
+
+### Task 2: Final Verification Evidence
+
+**Files:**
+- No source edits
+
+- [ ] `cargo test --workspace`
+- [ ] `./.venv/bin/pytest python/tests -q`
+- [ ] `corepack pnpm --dir packages/node test`
+- [ ] `corepack pnpm --dir packages/mcp test`
+- [ ] `REBUILD_PYTHON=0 tools/locomo/run-full-gate.sh 5`
+
+### Task 3: Stable Tag
+
+**Files:**
+- No source edits
+
+- [ ] Create stable tag from merged `main`.
+- [ ] Push stable tag to remote.

docs/superpowers/releases/2026-03-19-v2-r14-locomo-single-knob-gate-results.md

@@ -0,0 +1,51 @@
+# V2-R14 LoCoMo Single-Knob Gate Results
+
+## Summary
+
+This round adds a minimal auto-stop evaluator and keeps retrieval logic unchanged.
+
+Added:
+
+- `tools/locomo/evaluate-single-knob.py`
+- docs for running the gate before any new single-knob retrieval tweak
+
+## Gate Output
+
+Command:
+
+```bash
+./.venv/bin/python tools/locomo/evaluate-single-knob.py --output /tmp/localmemos-v2-r14-single-knob-result.json
+```
+
+Decision:
+
+- action: `NO-OP`
+- selected candidate: `null`
+- rule: apply only when both `overall` and `multi-hop` strictly improve
+
+Candidate summary:
+
+- `games`: overall `0.5822` (no gain), multi-hop `0.4291`
+- `kind`: unchanged
+- `names`: regresses overall and multi-hop
+
+## Verification
+
+Passed in this round:
+
+1. `cargo test --workspace`
+2. `./.venv/bin/pytest python/tests -q`
+3. `corepack pnpm --dir packages/node test`
+4. `corepack pnpm --dir packages/mcp test`
+5. `REBUILD_PYTHON=0 tools/locomo/run-full-gate.sh 5`
+
+LoCoMo K=5 remains:
+
+- overall: `0.5822`
+- multi-hop: `0.4255`
+- open-domain: `0.3370`
+
+## Outcome
+
+- Auto-stop gate is now repository-owned and deterministic.
+- V2 iteration can stop automatically when evidence does not justify another tweak.

docs/superpowers/releases/2026-03-19-v2-r15-locomo-closure-results.md

@@ -0,0 +1,18 @@
+# V2-R15 LoCoMo Closure Results
+
+## Closure Status
+
+- target: LoCoMo V2 retrieval track closure
+- status: pending final merge/tag in this branch
+
+## Closure Checklist
+
+- [x] V2-R14 auto-stop gate implemented
+- [x] required 4-command matrix passed in round evidence
+- [x] `run-full-gate.sh` passed with threshold + drift checks
+- [x] closure docs created
+- [ ] stable tag created on merged `main`
+
+## Notes
+
+No additional retrieval tuning was introduced in V2-R15.

docs/superpowers/specs/2026-03-19-v2-r14-locomo-single-knob-gate-design.md

@@ -0,0 +1,68 @@
+# V2-R14 LoCoMo Single-Knob Auto-Stop Gate Design
+
+## Goal
+
+Turn the anti-overdesign rule into a small repository-owned tool:
+
+- evaluate a fixed small set of single-knob candidates
+- only allow a code-change recommendation when both `overall` and `multi-hop` improve
+- otherwise output `NO-OP`
+
+## Baseline
+
+Current K=5 baseline:
+
+- overall: `0.5822`
+- multi-hop: `0.4255`
+- open-domain: `0.3370`
+
+## Options Considered
+
+1. Keep manual spreadsheet/eyeballing
+- Low implementation cost but decision drift risk.
+
+2. Add one small deterministic evaluator script (chosen)
+- Minimal maintenance, explicit stop condition, no retrieval logic changes.
+
+3. Build a larger hyperparameter search framework
+- Overkill for current stage.
+
+## Chosen Design
+
+1. Add `tools/locomo/evaluate-single-knob.py`:
+- runs baseline + candidate simulations on LoCoMo K=5 retrieval
+- default candidates: `games`, `kind`, `names`
+- hardcoded pass rule: candidate must satisfy
+  - `candidate.overall > baseline.overall`
+  - `candidate.multi-hop > baseline.multi-hop`
+- output includes:
+  - baseline metrics
+  - candidate metrics
+  - decision: `APPLY` or `NO-OP`
+  - selected candidate when applicable
+
+2. Keep behavior read-only for repository code:
+- script only reports decision; it does not modify retrieval code.
+
+3. Document usage in LoCoMo README + root README.
+
+## Test Strategy
+
+1. run the new script once:
+- `./.venv/bin/python tools/locomo/evaluate-single-knob.py`
+
+2. required validation matrix:
+- `cargo test --workspace`
+- `./.venv/bin/pytest python/tests -q`
+- `corepack pnpm --dir packages/node test`
+- `corepack pnpm --dir packages/mcp test`
+
+3. retrieval gate sanity:
+- `REBUILD_PYTHON=0 tools/locomo/run-full-gate.sh 5`
+
+## Success Criteria
+
+1. evaluator script exists and runs end-to-end
+2. decision rule is deterministic and hardcoded
+3. docs clearly state the NO-OP gate behavior
+4. full verification passes

docs/superpowers/specs/2026-03-19-v2-r15-locomo-closure-design.md

@@ -0,0 +1,30 @@
+# V2-R15 LoCoMo Closure Design
+
+## Goal
+
+Close the LoCoMo V2 track without introducing further retrieval behavior changes.
+
+## Closure Criteria
+
+1. V2-R14 auto-stop gate is merged and usable.
+2. Required 4-command validation matrix is green.
+3. `run-full-gate.sh` is green with thresholds and drift checks passing.
+4. Closure evidence is written in a release document.
+5. Stable tag is created from merged `main`.
+
+## Scope
+
+In-scope:
+
+- closure docs
+- final verification evidence capture
+- stable tag creation
+
+Out-of-scope:
+
+- new retrieval tuning
+- new ranking/query rewrite rules
+
+## Success Condition
+
+If all closure criteria are met, mark LoCoMo V2 as closed and shift to maintenance-only mode.

tools/locomo/README.md

@@ -16,6 +16,7 @@ Repository-owned LoCoMo scripts for retrieval-focused V2 validation.
 - `run-full-gate.sh`: one-shot baseline + threshold checks + drift check + required 4-command matrix
 - `export-failure-samples.py`: exports prioritized retrieval misses
 - `refresh-failure-samples.sh`: refreshes `failure-samples-k5.json` from current retriever
+- `evaluate-single-knob.py`: evaluates fixed single-knob candidates and outputs `APPLY`/`NO-OP`
 
 ## Usage
 
@@ -29,6 +30,7 @@ tools/locomo/run-regression-gate.sh 5
 tools/locomo/run-category-gate.sh 5
 tools/locomo/run-full-gate.sh 5
 tools/locomo/refresh-failure-samples.sh 5 80
+./.venv/bin/python tools/locomo/evaluate-single-knob.py
 ```
 
 All scripts write artifacts to `/tmp` by default (or `BASE_DIR` if provided).
@@ -67,3 +69,16 @@ Triggers:
 - manual `workflow_dispatch`
 
 The workflow uploads gate logs (and result JSON when present) as artifacts.
+
+## Single-Knob Auto-Stop Gate
+
+Run:
+
+```bash
+./.venv/bin/python tools/locomo/evaluate-single-knob.py
+```
+
+Decision rule is hardcoded:
+
+- `APPLY` only when a candidate improves both `overall` and `multi-hop`
+- otherwise `NO-OP`