docs(router): gemma-codemap validation run 2026-10-14

.router/2026-10-14-gemma-codemap-validation/evidence.md

@@ -0,0 +1,61 @@
+# Evidence: validate 7 improvements (2026-10-14, throwaway copies only)
+
+No live file edited. Live `~/.pi-pocket/config.json`, `skills.json`, routers, homelab config, `src/server` untouched. No server restart, no model load/evict initiated (embedding calls hit already-resident CPU models), no VM250/proxmox contact, no secret values printed (ownerToken redacted everywhere).
+
+## 0. Baseline (SEEN)
+
+- `src/server/reload.ts` ORDER (lines 29-47): `read-economy.ts`, `loop-guard.ts`, `pruner.ts`, `tool-repair.ts` are built-ins; `OFF_BY_DEFAULT={"guard.ts"}` only — the four batteries are on-by-default code, toggled via `enabledExtensions`.
+- Extension headers: `loop-guard.ts` (3rd identical call blocked, says so), `pruner.ts` (mask-then-maybe-summarize), `read-economy.ts` (≤500 lines + structural map), `tool-repair.ts` (repair JSON-string args before validation).
+- Live `config.json` `enabledExtensions`: `['artifacts.ts','codemode.ts','goals.ts','hq-mcp.ts','hq-router.ts','memory.ts','pip.ts','schedules.ts','subagents.ts','triggers.ts']` — the four batteries NOT enabled; `ownerToken`/hashes not quoted.
+- llama-swap config: `text-embedding-nomic-embed-text-v1.5` alias `embed` (Q4, CPU `-ngl 0`, ctx 2048, mean pooling); `embeddinggemma-2` alias `embed2` (Q8_0 310MiB, CPU, ctx 8192, mean pooling, trial alongside, undo = delete entry + group member line); both in non-exclusive persistent `embeddings` group. `Gemma4-26B-A4B-QAT` alias `gemma4-26b`, chat-group member, BF16-KV-only, no prefix reuse, top_k≤20, vision not wired, MTP full-head-only, load 34s / 17,454MiB @131072 (2026-10-13 aphotic comment).
+- `muse-router.json`: model `opencode-go/muse-spark-1.3-contributor`, thinking high, pipeline plan→implement→review→fix→ship with skills poteto-mode/blast-radius/unslop.
+- `skills.json` keys (19): router 21, plan 20, coder 13, agent 10, review 12, writer 5, thinker 4, uncensored 9, agent-fast 2, coder-fast 3, fast-plan 20, fast-coder 13, fast-agent 10, fast-writer 5, strata-* 5 roles. `coder` list verified (13 skills incl. codebase, repo-work, tdd).
+- `hq-router.ts`: `router-fast`→ROUTER-FAST.md; FAST_BLOCKED={bash,edit,write}; block is per-conversation via `fastRouters` set keyed by **model id** `router-fast` (`id === "router-fast"` in hq_router section render); skill-trim from skills.json by `<!-- hq-role: name -->`, `/skill:<name>` unaffected.
+- ROUTER-FAST.md: dispatcher read-only (bash/edit/write blocked), width 1, paths-not-contents, `<run>/log.tsv` stage log.
+
+## 1. embed2 cutover — VALIDATED (copy-DB)
+
+- TESTED: both endpoints live on loopback :9090: nomic dim **768**, gemma dim **768** (measured via `/v1/embeddings`, not assumed).
+- TESTED: copy DB reindex under gemma only: `CODEVEC_DB=/tmp/codevec-copy.db CODEVEC_EMBED_MODEL=embeddinggemma-2 index_repo(omp-copy, /home/tcrypt/projects/oh-my-pocket)` → 273 files, 2334 chunks, no error.
+- VALIDATED (with one contaminated query — see next line): same 3 queries on copy-DB hit sane files: "loop guard…"→handoff.sample.json; "read economy…"→test/read-economy.test.ts:1-60; "router stage prompt"→src/server/routers.ts:1-60.
+- CONTAMINATED (fix 2026-10-14): Q1 ("loop guard…") top-hit `handoff.sample.json` — a file this run itself wrote, indexed as part of the 273-file copy (run folder was inside the indexed tree), so Q1 is circular. Q2–Q3 hit real product files, dims (768/768) plus the 2334-chunk reindex are solid, so VALIDATED-on-copy stands on Q2+Q3. Required before any production cutover decision: re-run Q1 with `.router/` excluded from the indexed tree (or quote a product-file hit for the same query terms).
+- UNCLEAR (stated, not guessed): whether pre-existing nomic vectors stay comparable under gemma cosine — codevec_mcp.py comment says re-index required; copy test re-indexed from scratch so comparability untested. Cutover recommendation: keep `embed` alias until a mixed-DB test passes. Undo: delete `embeddinggemma-2` entry + embeddings-group member line (config comment). PROVEN not claimed (no `git diff --stat` of production hunks — nothing applied).
+
+## 2. Index coverage — TESTED (gap found, live DB untouched)
+
+- `list_repos` → exactly **1 repo: homelab** (1108 files, 4703 chunks, indexed 2026-10-14T13:53:51Z). **oh-my-pocket is NOT indexed** in the live DB — coverage gap.
+- Live-DB `search_code(repo:homelab)`: "loop guard…" hit harnesses/pi/extensions/loop-guard.ts (stale Pi harness copy, not Pi Pocket's); "read economy…" MISSED (top hits unrelated audit/economy docs); "router stage…" hit hq-router.ts. So Pocket code is unsearchable live.
+- Copy-DB (`omp-copy`, gemma): all 3 queries hit Pocket files (see §1). VALIDATED-on-copy that indexing fixes it; live `index_repo` NOT run (deferred, needs operator decision + embedder choice).
+- `git ls-files | wc -l` = 299 vs copy-index 273 files (SKIP_DIRS/.md-filter explain delta; not investigated further).
+
+## 3. Batteries — TESTED + unit-VALIDATED (per-behavior exercises pending)
+
+- TESTED: `node test/serve.ts` copy boots clean on 127.0.0.2:8899 twice (logs show sign-in links, no errors).
+- unit-VALIDATED: throwaway `openApp(scriptedModel())` + `setExtensionEnabled` for all four → loader names `pocket-read-economy, pocket-loop-guard, pocket-pruner, pocket-tool-repair` all present (1/1 pass).
+- unit-VALIDATED: unit tests `loop-guard + pruner + read-economy` 33/33 pass; `app.test.ts` 32/32 pass (covers guard toggle path).
+- Rating wording fix (2026-10-14, per review finding 5): unqualified VALIDATED overstated against plan step 3's bar (VALIDATED = steps 2–4 all pass on the copy, where step 3 is the four per-behavior exercises). Correct rating is **TESTED + unit-VALIDATED** until the implement stage runs the four behaviors on the copy.
+- Per-behavior UI exercises (500-line map, malformed-call repair, triple-call block, prune note) NOT run — scripted model + no browser; stated as not verified. Production undo: Menu → Extensions off (no file change; built-ins stay in ORDER).
+
+## 4. muse-router fast path — TESTED (candidate in run folder)
+
+- `muse-router-fast.json` drafted in run folder only; `json.load` parses ("json ok").
+- CONFIRMED CONSTRAINT (fix 2026-10-14, was UNCLEAR — code path verified per review finding 2, `hq-router.ts` ll.117-130, 172-180): dispatcher block keys off **model id** `router-fast`, not router-editor id. `fastRouters` only ever contains conversations whose last rendered router model id was literally `router-fast`. A new `muse-router-fast` router id running on a cloud model gets **no tool block** without either (a) running on model `router-fast`, or (b) a code change extending `PROMPTS`/`routerModel()` id matching. Do not claim width-1/dispatcher behavior for the new id until one of those lands.
+- Safe side (verified, not previously recorded): the skill-trim side does NOT break for the new id — `hqRole` (`hq-router.ts` ~91-104) returns `"router"` for any router-editor session on any model, and `"router"` exists in `skills.json` (21 skills). So the new id gets the router skill list, just no tool block.
+- Copy-server stage-dispatch dry run NOT performed (needs router session on copy; stated as not verified).
+
+## 5. Per-role skills — TESTED
+
+- SEEN: counts per role (see §0), trim source `skills.json[hq-role]`, renderer `hq-router.ts` wrapSection("skills"), roles source `~/homelab/harnesses/agents/roles/` (roles.yaml + per-role md) rendered by `~/homelab/scripts/agents/apply_roles.py` — path confirmed (`ls` both dirs).
+- Trimmed-list == skills.json[role] check NOT run on copy (needs cloud-model session render; stated as not verified). Token delta not measured on copy (not exposed); code-level estimate stands (102 skills ~6.8K tokens → role list).
+
+## 6. Typed handoffs — TESTED
+
+- `handoff.schema.json` + `handoff.sample.json` written in run folder; `json.load` both ("schema+sample ok").
+- Sample carries goal/project/worktree/findings[file:line:claim]/nextSteps/outOfScope.
+- Consumption test (plan-shaped stage reading sample on copy) NOT run — stated as not verified. Production home open choice: (a) convention-only prompt text, (b) template beside ROUTER*.md, (c) enforced schema in hq-router.ts.
+
+## 7. Gemma4 decision — SEEN + prior-run TESTED (no load by this plan)
+
+- SEEN: block quoted (§0). Prior-run measurements (config comment, 2026-10-13 aphotic): load 34s, 17,454MiB @131072, tool_calls correct args — recorded as TESTED-by-prior-run, not re-proven.
+- TESTED (read-only): `git log --oneline -5 -- reference/llama-swap/config.yaml` → 03f3b16, 9d19163, a69c4da, 121f08f, 646c7e0; `Gemma4-26B-A4B-QAT` entry + chat-group member line present.
+- Decision matrix: (a) adopt as router/NInfer role — blocked on prefix-reuse + vision gaps; (b) opt-in alias for text/tool trials on copy — viable now; (c) defer. Copy-server session on gemma id explicitly OUT OF SCOPE (implement stage's first step); no load/evict performed here.

.router/2026-10-14-gemma-codemap-validation/fix.md

@@ -0,0 +1,30 @@
+# Fix report: gemma-codemap review findings (2026-10-14)
+
+Run-folder only. No live config/skill/router/src edit, no restart, no model load, no VM250 contact, no secrets printed.
+
+## Finding 1 — `muse-router-fast.json` dispatcher object dropped by loader
+- Changed: top-level `"dispatcher": {blockedTools..., note...}` → `"dispatcher": true`, plus a `_dispatcherNote` sidecar string carrying the width-1 intent, blockedTools list, and the real enforcement pointer (`hq-router.ts` `fastRouters` keyed on model id `router-fast`).
+- Proof: `node` eval of the exact loader expression from `src/server/routers.ts:541` (`...(raw.dispatcher === true ? { dispatcher: true } : {})`) against the fixed file → `loader keeps dispatcher: {"dispatcher":true}`. Before the fix the object form failed the `=== true` check and was stripped silently.
+
+## Finding 2 — fast-id tool block absent, skill side safe
+- Changed: `evidence.md` §4 rewritten from "UNCLEAR … finding" to **CONFIRMED CONSTRAINT** (code path `hq-router.ts` ll.117-130, 172-180 verified: `fastRouters` only contains conversations whose last rendered router model id was literally `router-fast`; new id `muse-router-fast` on a cloud model gets no tool block without running on model `router-fast` or extending `PROMPTS`/`routerModel()` id matching). Added the verified safe side: `hqRole` (~91-104) returns `"router"` for any router-editor session on any model and `"router"` exists in `skills.json` (21 skills) — new id gets the router skill list, just no tool block.
+- Proof: code re-read at the cited lines during this fix; `muse-router-fast.json` `_dispatcherNote` now names the same enforcement point so a future copy-paste into `~/.pi-pocket/routers/` carries the warning.
+
+## Finding 3 — `handoff.sample.json` line refs wrong
+- Changed: finding 1 `src/server/reload.ts:42` → `:44`; finding 2 `loop-guard.ts:1` → `:2` with the claim text noting the behavior sentence spans lines 2-3 (schema requires integer `line`, so the range lives in the claim, not the number).
+- Proof: `sed -n '43,45p' src/server/reload.ts` → line 44 is `"loop-guard.ts",`; `sed -n '2,3p' src/server/extensions/loop-guard.ts` → the third-identical-call-blocked sentence. Schema check passes: required keys (`goal, project, findings, nextSteps`; per-finding `file, line, claim`) present and `line` is int — a `{"file","claim"}`-without-`line` object would now fail this check, closing the "parses fine while violating required" gap the review demonstrated.
+
+## Finding 4 — embed2 Q1 self-referential hit
+- Changed: `evidence.md` §1 VALIDATED line qualified; added explicit CONTAMINATED note: Q1 ("loop guard…") top-hit `handoff.sample.json`, a file this run authored inside the indexed 273-file copy tree — 1 of 3 queries circular. VALIDATED-on-copy now rests on Q2+Q3 (real product files) + 768/768 dims + 2334-chunk reindex.
+- Proof/required follow-up (stated in evidence, not runnable from here without reindexing a copy): re-run Q1 with `.router/` excluded from the indexed tree before any production cutover decision. Mixed nomic+gemma vector comparability remains UNCLEAR as before.
+
+## Finding 5 — batteries VALIDATED overstates plan bar
+- Changed: `evidence.md` §3 heading/rating → **TESTED + unit-VALIDATED (per-behavior exercises pending)** with the reasoning (plan step 3 requires the four per-behavior exercises: 500-line map, malformed-call repair, triple-call block, prune note — explicitly not run, no browser/scripted-model UI run). Same one-line correction applied to the Ratings line in `implement.md`.
+- Proof: nothing hidden — the "not verified" list already said so; only the rating word changed.
+
+## Tests rerun
+- `node --test test/loop-guard.test.ts test/pruner.test.ts test/read-economy.test.ts` → **33/33 pass**.
+- `node --test test/app.test.ts` → **32/32 pass**.
+- `git status --short` → only untracked `.router/` + pre-existing untracked `.zvec-grep/`; `git diff --stat` empty (zero tracked-file modifications).
+
+SELF-CHECK: each of the 5 review findings fixed in the run folder only (fast JSON dispatcher true, handoff line refs, evidence wording batteries TESTED+unit-VALIDATED, embed2 Q1 contamination + rerun note, fast-id confirmed-constraint + skill-safe note); proofs run and outputs read (loader expr, schema check, sed line verification, 33/33 + 32/32 tests, git status clean); no live config/skill/router/src edit, no restart, no model load/evict, no VM250/proxmox contact, no secrets printed.

.router/2026-10-14-gemma-codemap-validation/handoff.sample.json

@@ -0,0 +1 @@
+{"findings":[{"claim":"Loop-guard ORDER position (line 44), after read-economy (line 43); built-in, opt-in via Extensions sheet","file":"src/server/reload.ts","line":44},{"claim":"Third exactly identical tool call in one turn is blocked, and the block says so (behavior sentence, lines 2-3)","file":"src/server/extensions/loop-guard.ts","line":2}],"goal":"Validate loop-guard battery on copy server","instructionFiles":["docs/self-editing.md"],"nextSteps":["Enable loop-guard on copy Extensions sheet","Run three identical failing calls, confirm third blocked"],"outOfScope":["Live config.json edit"],"project":"oh-my-pocket","worktree":"/home/tcrypt/projects/oh-my-pocket"}

.router/2026-10-14-gemma-codemap-validation/handoff.schema.json

@@ -0,0 +1 @@
+{"$schema":"http://json-schema.org/draft-07/schema#","description":"Typed handoff between muse-router stages. Paths, not contents; every claim carries file:line.","properties":{"findings":{"items":{"properties":{"claim":{"type":"string"},"file":{"type":"string"},"line":{"type":"integer"}},"required":["file","line","claim"],"type":"object"},"type":"array"},"goal":{"type":"string"},"instructionFiles":{"items":{"type":"string"},"type":"array"},"nextSteps":{"items":{"type":"string"},"type":"array"},"outOfScope":{"items":{"type":"string"},"type":"array"},"project":{"type":"string"},"worktree":{"type":"string"}},"required":["goal","project","findings","nextSteps"],"title":"muse-router handoff","type":"object"}

.router/2026-10-14-gemma-codemap-validation/implement.md

@@ -0,0 +1,38 @@
+# Implement report: gemma-codemap validation (2026-10-14)
+
+Validation-only. No production file changed: `git status --short` shows only untracked `.router/` (this run) and pre-existing untracked `.zvec-grep/`; zero modifications to tracked files. (`.zvec-grep/` is not mine — never wrote there.)
+
+## What changed (run folder only, all new files)
+
+- `.router/2026-10-14-gemma-codemap-validation/evidence.md` — per-improvement SEEN/TESTED/VALIDATED log (the full record; see it, not this file, for quotes and numbers).
+- `.router/2026-10-14-gemma-codemap-validation/muse-router-fast.json` — fast-path candidate draft (parses; NOT registered).
+- `.router/2026-10-14-gemma-codemap-validation/handoff.schema.json` + `handoff.sample.json` — typed-handoff schema + sample (both parse).
+- `.router/2026-10-14-gemma-codemap-validation/plan.md` — input (pre-existing).
+- This file.
+
+## Commands + key output
+
+- Baseline reads: ORDER/batteries headers quoted; live `enabledExtensions` = 10 drop-ins, four batteries absent; embed2 + Gemma4 config blocks quoted; `muse-router.json` pipeline plan→implement→review→fix→ship; `skills.json` 19 roles (coder=13 skills); `hq-router.ts` fast-block + skill-trim logic read.
+- Embed dims (loopback :9090, resident CPU models, no load initiated): nomic **768**, gemma **768**.
+- Copy-DB reindex under gemma (`CODEVEC_DB=/tmp/codevec-copy.db`, MCP stdio): 273 files, 2334 chunks. Same 3 queries hit `test/read-economy.test.ts`, `src/server/routers.ts` (+ own sample file). → embed2 VALIDATED on copy.
+- `list_repos` (live): only `homelab` (1108 files, indexed today) — **oh-my-pocket unindexed, coverage gap**; live "read economy" query MISSED.
+- Copy server `node test/serve.ts` booted clean twice on 127.0.0.2:8899 (sign-in links, no errors).
+- Throwaway enable test (scripted model, temp data): all four batteries → loader names present, 1/1 pass. Deleted after.
+- Unit tests: loop-guard+pruner+read-economy **33/33**; `app.test.ts` **32/32**.
+- Fast-path constraint found: `hq-router.ts` block keys off model id `router-fast`, not router id — new `muse-router-fast` id gets no tool block without running on `router-fast` model or a code change.
+- Gemma4: git log 5 entries + entry/member lines present (read-only); prior-run load figures recorded, not re-proven; no load/evict here.
+- Cleanup: copy servers killed (temp data auto-deleted), `/tmp/codevec-copy.db` + temp req/test files removed.
+
+## What not verified
+
+- Nomic-vs-gemma vector comparability in a mixed DB (copy test re-indexed from scratch).
+- Live `index_repo` for oh-my-pocket (deferred to operator: needs embedder choice).
+- Per-behavior battery exercises (500-line map, malformed-call repair, triple-call block, prune note) — no browser/scripted-model UI run.
+- Copy-server stage-dispatch dry run for fast path; skill-trim render on a cloud-model session + token delta; handoff consumption test by a plan-shaped stage.
+- Gemma4 copy-server multi-turn + tool-call transcript (implement stage's first step; GPU shared).
+
+## Ratings
+
+embed2 VALIDATED (copy; Q1 marked contaminated, re-query with .router/ excluded required before cutover) · coverage TESTED (gap found) · batteries TESTED + unit-VALIDATED (per-behavior exercises pending) · fast-path TESTED (constraint confirmed: block keys off model id router-fast; skill-trim safe for new id) · skills TESTED · handoffs TESTED (sample line refs corrected) · gemma4 SEEN + prior TESTED.
+
+SELF-CHECK: plan followed step by step; only throwaway copies touched (copy server temp dirs, CODEVEC_DB=/tmp/...); no live config/skill/router/src edit, no restart, no model load/evict, no VM250/proxmox contact, no secrets printed; proof commands run and outputs read; tests 33/33 + 32/32 + 1/1 green; git status confirms no tracked-file changes; evidence.md written with UNCLEAR items stated, not guessed.