docs: CLAUDE.md current-state entry for v1.108.164

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jgravelle

CLAUDE.md

@@ -1,7 +1,8 @@
 # jcodemunch-mcp — Project Brief
 
 ## Current State
-- **Version:** 1.108.163 — **Audit P2 pair closed: WS-8 license-key transport (V12) + WS-7 benchmark integrity (V1).** **WS-8:** `org/license._check_server` now POSTs `{product, license}` as a form body (key NEVER in the URL → can't land in server/proxy access logs); `cli/install_pack` carries the key in the `X-JCM-License` header. Each has a ONE-SHOT legacy fallback keyed to the exact pre-deploy backend signature ("Missing license parameter." for validate.php POST; the no-license 403 "requires a jCodeMunch license" for packs) so ship order can't strand a paying customer — a REAL key rejection (not found/revoked/expired/"Invalid or expired") never retries. Backend CONFIRMED POST/header-aware on j.gravelle.us 2026-07-23 (live curl verification, all transports) — the two client fallbacks (`_needs_legacy_get_fallback`, `_looks_like_missing_license_response`) can be removed in a future release. Backend mirror EDITED (jjg deploys via SFTP): `C:\MCPs\web\jCodeMunch.com\validate.php` (POST form/JSON body + X-JCM-License header + legacy GET; Cache-Control: no-store) + `starter-packs-system/api/index.php` (`request_license()` helper on download/validate; internal `validate_license()` now POSTs to validate.php). NOTE: root `C:\MCPs\web\validate.php` copy is STALE (pre-jbuffer, May 16) — canonical mirror is `jCodeMunch.com\`. Bonus fix: install-pack's `raise_for_status()` rendered every 4xx JSON license/pack error as "Could not reach the starter packs server" — removed; JSON error branch now actually runs. **WS-7:** `benchmarks/results.md` REGENERATED at .163 against same-day GitHub re-indexes (express 172 / fastapi 1,000 / gin 109 files): **99.6% aggregate** (5,799,695→25,220 tok, 230x), per-query 99.1–99.9%; hand-written A/B sections preserved verbatim (regen→scratch→merge). README headline RECONCILED — the stale "95% average" table (old 34-file capped express index) replaced; README/results.md/METHODOLOGY.md/provenance measured.json all quote 99.6% now (provenance registry itself unchanged — it pins average_pct 99.6 which held; drift-guard test green). "95%+" floor phrasing elsewhere kept (conservative, true). Harness dead fallback fixed (`get_file_content_text` never existed → `store.get_file_content`). `benchmarks/token_baselines/v1.108.163.json` captured (in-process driver; NOTE `__version__` is "unknown" under bare PYTHONPATH — driver stamps version explicitly) → `analyze_perf(compare_release="1.108.163")` resolves. Replay CI gate was already wired (replay.yml, 2% gate) — WS-7 acceptance met. WS-8 CI siblings (SHA-pinned sign-release, dependabot github-actions) verified already done; `uv sync --locked` still deliberately parked (uv.lock drifted). Tests `tests/test_v1_108_163.py` (28 w/ params); suite 5569 passed + the known 12 local-ONNX semantic env fails. **Audit P2 queue now EMPTY — remaining audit work is P3s only.**
+- **Version:** 1.108.164 — **A path-shaped `repo` arg returns a routed error instead of a raw storage crash (#376, split out of #375; reported from a daily Ubuntu install).** `tools/_utils.resolve_repo` split any `repo` containing `/` on the FIRST separator and returned the halves UNVALIDATED (`_utils.py:117`), so `repo="src/auth/service.ts"` → `owner="src"`, `name="auth/service.ts"`. Callers DO catch `ValueError` from the resolver (`search_symbols.py:626`), but the bad pair then reached `store.load_index` and raised `ValueError: Path separator in name` from `SQLiteIndexStore._safe_repo_component` (`sqlite_store.py:2881`) — **outside every handler**. Since `_safe_repo_component` rejects a separator in `name` at WRITE time, an `owner/name` id can never legitimately carry a second one, so **every two-slash `repo` argument was a guaranteed crash**, on every tool routing through the shared resolver (not just search_symbols). Reproduced on .163, not only the reporter's .158. Fix: a post-split name still containing `/` or `\` is treated as a path — routed to `_resolve_path_repo` first (which now also picks up bare relative MULTI-SEGMENT paths like `apps/web/src` that `_looks_like_path` is deliberately too conservative to match, v1.108.159's acceptance only covered `.`/`~`/backslash/absolute), else raises new `_path_shaped_repo_error` naming `resolve_repo` + `index_folder` + **`file_pattern=` when the arg has a file suffix** (the reporter's ask — an agent passing `repo=<file>` usually meant to scope the search). `_resolve_path_repo`'s unindexed-path raise routes through the same helper so both give one message. **Single-separator ids byte-identical** (`tools/agents.ts` still takes the id path → clean in-band not-loadable error). New `tests/test_v1_108_164.py` (8, incl. the single-slash no-regression guard). NO schema/tool-count/INDEX_VERSION change. Suite 5577 passed + the known 12 local-ONNX semantic env fails.
+- **Prior (1.108.163):** — **Audit P2 pair closed: WS-8 license-key transport (V12) + WS-7 benchmark integrity (V1).** **WS-8:** `org/license._check_server` now POSTs `{product, license}` as a form body (key NEVER in the URL → can't land in server/proxy access logs); `cli/install_pack` carries the key in the `X-JCM-License` header. Each has a ONE-SHOT legacy fallback keyed to the exact pre-deploy backend signature ("Missing license parameter." for validate.php POST; the no-license 403 "requires a jCodeMunch license" for packs) so ship order can't strand a paying customer — a REAL key rejection (not found/revoked/expired/"Invalid or expired") never retries. Backend CONFIRMED POST/header-aware on j.gravelle.us 2026-07-23 (live curl verification, all transports) — the two client fallbacks (`_needs_legacy_get_fallback`, `_looks_like_missing_license_response`) can be removed in a future release. Backend mirror EDITED (jjg deploys via SFTP): `C:\MCPs\web\jCodeMunch.com\validate.php` (POST form/JSON body + X-JCM-License header + legacy GET; Cache-Control: no-store) + `starter-packs-system/api/index.php` (`request_license()` helper on download/validate; internal `validate_license()` now POSTs to validate.php). NOTE: root `C:\MCPs\web\validate.php` copy is STALE (pre-jbuffer, May 16) — canonical mirror is `jCodeMunch.com\`. Bonus fix: install-pack's `raise_for_status()` rendered every 4xx JSON license/pack error as "Could not reach the starter packs server" — removed; JSON error branch now actually runs. **WS-7:** `benchmarks/results.md` REGENERATED at .163 against same-day GitHub re-indexes (express 172 / fastapi 1,000 / gin 109 files): **99.6% aggregate** (5,799,695→25,220 tok, 230x), per-query 99.1–99.9%; hand-written A/B sections preserved verbatim (regen→scratch→merge). README headline RECONCILED — the stale "95% average" table (old 34-file capped express index) replaced; README/results.md/METHODOLOGY.md/provenance measured.json all quote 99.6% now (provenance registry itself unchanged — it pins average_pct 99.6 which held; drift-guard test green). "95%+" floor phrasing elsewhere kept (conservative, true). Harness dead fallback fixed (`get_file_content_text` never existed → `store.get_file_content`). `benchmarks/token_baselines/v1.108.163.json` captured (in-process driver; NOTE `__version__` is "unknown" under bare PYTHONPATH — driver stamps version explicitly) → `analyze_perf(compare_release="1.108.163")` resolves. Replay CI gate was already wired (replay.yml, 2% gate) — WS-7 acceptance met. WS-8 CI siblings (SHA-pinned sign-release, dependabot github-actions) verified already done; `uv sync --locked` still deliberately parked (uv.lock drifted). Tests `tests/test_v1_108_163.py` (28 w/ params); suite 5569 passed + the known 12 local-ONNX semantic env fails. **Audit P2 queue now EMPTY — remaining audit work is P3s only.**
 - **Prior (1.108.162):** — **Canonical handoff contract: `finalize_handoff` + `munch://handoff/<id>` (#374, @mightydanp, CLOSED).** Server-owned canonical final handoff (`jcodemunch.handoff/v1`, shape 3 as accepted): the assistant AUTHORS the analysis; new `handoff.py` owns deterministic assembly (caller sections + named appendices, each exactly once, dup names rejected), session-scoped in-memory persistence (process == session, `_steer_state` precedent, `clear_handoffs()` test hook), identity (`handoff_id = sha256(body)[:16]` — same inputs ⇒ same body/id/hash), and immutable serving. **Marquee = evidence attestation:** `evidence_refs` validate against the session retrieval record — new `token_tracker.served_symbol_ids()` snapshot of the v1.108.146 yield tracker (populated by search_symbols/get_ranked_context `note_served`); a ref = served symbol id OR its file path; unknown refs → in-band error dict → `CallToolResult(isError=True)` + `unknown_refs` + hint (v1.108.74 contract). Receipt `{schema, handoff_id, resource_uri, sha256, length(bytes utf-8), canonical:true(ADVISORY only), evidence_count, appendices}`. Resource follows the #371 pattern: `list_resources()` appends per-handoff rows, `read_resource()` resolves `munch://handoff/<id>` → text/markdown, unknown → ValueError. Registration: all surfaces (_CANONICAL_TOOL_NAMES / Session-Aware Routing category / _TOOL_TIER_STANDARD / Tool schema / dispatch / config.py all_tools ×2); counter `STATE_CHANGING_ACTIONS` (order needs allow_state_change=true; readOnlyHint:false derives) + `EXAMPLES` entry (live-schema-validated). Standard tier — core_compact unchanged (baseline refreshed: core_compact 3996, still <4000 live-ceiling). Tool count **90 → 91** full (test_server counts + expected-names bumped). No char limit, no repo writes, nothing persisted to disk. README "Canonical handoff" section. Tests `tests/test_v1_108_162.py` (22, modeled on the reporter's own citations: v1_108_74 shapes / v1_108_152 resource / counter example parity); suite 5528. **Suite parity (jdoc/jdata) = eventual, versioned contract, NOT a blocker; memory [[project-handoff-contract]] updated.**
 - **Prior (1.108.161):** — **BM25 tokenizer: Unicode word splitting + CJK character bigrams (suite parity with jdoc v1.114.1 / jdata v1.23.1; jdoc #91 class, @tetiz123).** `search_symbols._TOKEN_RE` was `[a-zA-Z0-9]{2,}` — every non-ASCII char a separator, so CJK symbol names/summaries/docstrings produced ZERO BM25 tokens (lexical channel dead for those corpora) and accented Latin mangled (`café`→`caf`). Fix: `_TOKEN_RE=[^\W_]+` + new `_CJK_RE` (Hangul Jamo/compat/syllables, Hiragana/Katakana+ext, Han unified+ExtA+compat) space-pads runs pre-split (mixed-script tokens split cleanly), then pure-CJK tokens expand to overlapping character bigrams via `_cjk_bigrams` (lone char passes through; the <2 length filter now applies to non-CJK only); CJK tokens skip stemming/abbreviation (English-only). Same expansion at index + query time (both route through `_tokenize`) ⇒ bigram overlap is the match signal. ASCII tokenization byte-identical (camel split/stem/abbrev intact — replay golden unaffected). NO reindex (BM25 tokenizes stored fields at scoring time), NO schema/tool-count/INDEX_VERSION change. Tests `tests/test_v1_108_161.py` (8); full suite 5506 passed.
 - **Prior (1.108.160):** — **Multi-checkout "different working tree" responses (bench fix-list item 3 — LAST open bench-arc item).** A second checkout of an already-indexed origin resolved via git identity to the SIBLING's index (`resolve_repo` → `indexed:true` w/ the other checkout's source_root; `index_file` → generic "run index_folder on the parent" → agent re-indexed ~3k files in-run, \$5.64 vs \$2.90 tainted rep). Two surfaces: **(1)** `resolve_repo._attach_working_tree_mismatch` (called ONLY on the `computed_repo_id` slow path — fast paths contain by construction) attaches `working_tree_mismatch:true` + `warning` (both checkouts + remedies) + `_meta.working_tree {queried_path, indexed_root}`; **(2)** `index_file._sibling_checkout_error` fires when best_match is None: `_find_git_root` → `_compute_repo_id` → `inspect_index`; index present w/ DIFFERENT source_root → "Different working tree detected" + cheap remedy first (query existing repo id read-only) + `index_folder(path=<root>, identity_mode='local')`, explicitly warns against re-indexing under the existing identity; `skipped:"different_working_tree"`. Same-checkout/not-indexed paths byte-identical. NO schema/tool-count/INDEX_VERSION change. New `tests/test_v1_108_160.py` (7). **Bench fix list FULLY CLOSED: (1) steering SHIPPED+MEASURED, (2) arg-mapping SHIPPED, (3) THIS, (2b) CLOSED AS DONE (jjg 2026-07-23 — .159 path acceptance + .158 informed-retry cover it; no cwd auto-defaulting, wrong-repo risk stands). Remaining lever = WS-7 matrix.** ([[project_lc_harness_jcm_arm]])