Token layer gaps: routing rules, recipe limits and E1/E2 receipt errata from the 2026-09-27 verdict wave

docs/token-practice.md

@@ -240,6 +240,52 @@ Run role-specific acceptance where applicable; guidance and research catalog
 entries are not implied executable deployments. Preserve failed quality gates
 when importing new matched-task or retrieval evaluations.
 
+## Counts, comparisons and acceptance (2026-09-27)
+
+These rules follow from the 2026-09-27 per-tool verdict wave and the review of the
+E1 and E2 subagent receipts.
+
+- **An invocation count is not a success rate.** A scan of native histories that
+  matches command text or MCP server names counts attempts. Report each population
+  with its own denominator. A subgroup, such as the children that received the
+  token-lanes block, is part of its population, not another one, and its rate is
+  neither general coverage nor a causal effect. Successful use on eligible tasks is
+  what the [preregistered E2E](../evidence/artifacts/token-adoption-e2e-20260926/README.md)
+  measures (M1, M6c, M7 and M8). It has not run, so no tool has an eligible-task
+  success rate yet.
+- **A comparison needs its task's acceptance.** A token difference counts only with
+  the check that the smaller output still answers its task. One Context Hub fact
+  does not make its document current; an ast-grep call match does not establish
+  outline or rule-configuration fidelity; one MarkItDown HTML conversion says nothing
+  about other formats or extensions; a Serena Python fixture does not establish
+  complete references in another language. The
+  [handbook's upstream limits](token-session-handbook.md#known-upstream-limits-behind-the-lanes)
+  give the routing.
+- **Count the recovery read.** Filtered or compressed output is not raw output. In
+  the [laptop run](../evidence/artifacts/token-e2e-ultracode-laptop-20260926/README.md),
+  the verifier refuted RTK's "no fact lost" claim (a misreported branch list and
+  shortened recall pointers), and Headroom's compression plus its full retrieval came
+  to more tokens than the original. Include recall or original reads and the response
+  envelope when comparing workflow cost; the clean-prefix Headroom figures below show
+  the same growth.
+- **Measurement infrastructure saves nothing itself.** gpt-tokenizer 3.4.0
+  (`o200k_base`) is the counter behind the exact comparisons, not a reducer. Its
+  counting contract covers ordinary UTF-8 text under the default special-token
+  policy, which disallows every special token and throws on an input that contains
+  one ([3.4.0 README](https://github.com/niieani/gpt-tokenizer/blob/3.4.0/README.md#special-tokens));
+  allowed-special modes are not qualified here, and neither is 4.0.0. ccusage totals
+  are consumption, reported token-only while any model is unpriced
+  ([recipe row](../recipes/README.md#component-catalog-install-and-check)). An
+  agentsview answer observes retained history, and MCPorter is transport.
+- **Receipts carry their current acceptance.** The E1 (#296) and E2 (#316) receipts
+  now hold dated adjudications. Of E1's sixteen exercised tools, QMD and Repomix
+  were retracted, ai-memory's check was vacuous, and the rest are partial because
+  no E1 check recorded a failing run. E2 keeps Context Mode, jCodeMunch, QMD and
+  ast-grep partial for the same reason
+  ([E1 correction](../evidence/artifacts/token-e2e-ultracode-20260925/README.md#results),
+  [E2 erratum](../evidence/artifacts/token-e2e-ultracode-laptop-20260926/README.md#erratum-2026-09-27)).
+  Read `tools[].adjudication`, not `quality_check.passed`.
+
 ## Shared Codex quota (2026-09-26)
 
 `scripts/codex_quota.py` reads the Codex account's usage snapshot through the

docs/token-session-handbook.md

@@ -153,19 +153,19 @@ per segment; choose Context Mode for large output needing processing.
 | [`context-mode`](https://github.com/mksglu/context-mode) | Native plugin/MCP on demand; configured lifecycle hooks automatic. Codex: the user-scope server that the worker lane writes, bound to each session's own directory | `ctx_execute_file` reads the selected project file; `ctx_stats` uses this server/session scope; [executor and session-store limits](#context-mode-executor-and-session-store); Codex: `codex mcp get context-mode --json` shows `"cwd": null` |
 | [`headroom`](https://github.com/chopratejas/headroom) | On-demand offline selected-artifact MCP compression/retrieval; no native prompt interception established | `headroom_compress` then `headroom_retrieve`; include recovery cost; `headroom savings --json` |
 | [`jcodemunch-mcp`](https://github.com/jgravelle/jcodemunch-mcp) | Local-scope (project-scoped) native MCP: explicitly index selected code, search, retrieve returned symbol ID; [F6 scope decision](decisions/2026-09-26-token-practice-f1-f9.md#f6-jcodemunch-scope-2026-09-26) | `order` actions `get_session_stats`, `search_symbols`, `get_symbol_source`; compare exact original |
-| [`qmd`](https://github.com/tobi/qmd) | On-demand CLI, named BM25 index/collection | `qmd --index "$QMD_INDEX" status`; update changed docs; search then get returned URI |
+| [`qmd`](https://github.com/tobi/qmd) | On-demand CLI, named BM25 index/collection | `qmd --index "$QMD_INDEX" status`; update changed docs; search then get returned URI; over MCP, typed `lex` searches with `rerank: false` ([limits](#known-upstream-limits-behind-the-lanes)) |
 | [`serena`](https://github.com/oraios/serena) | Native MCP symbols/references; project language servers | `get_current_config`, `find_symbol`; test actual Python/TypeScript/CJS file support |
 | [`socraticode`](https://github.com/giancarloerra/SocratiCode) | Native MCP semantic search; automatic watcher while adopted owner runs | `codebase_health`, `codebase_status({projectPath})`, exact search; watcher behavior needs actual change evidence |
 | [`ai-memory`](https://github.com/akitaonrails/ai-memory) | Native MCP retrieval; project-marker-gated lifecycle capture automatic | `memory_status`, scoped page read and fresh event metadata; durable writes deliberate |
-| [`repomix`](https://github.com/yamadashy/repomix) | On-demand selected-file handoff | `repomix "$PROJECT_ROOT" --include "$SELECTED_FILES" --compress --output "$PACK_FILE"`; compressed output omits implementation details |
+| [`repomix`](https://github.com/yamadashy/repomix) | On-demand selected-file handoff | `repomix "$PROJECT_ROOT" --include "$SELECTED_FILES" --compress --output "$PACK_FILE"`; compressed output omits implementation details and can drop a whole multi-line definition ([limits](#known-upstream-limits-behind-the-lanes)) |
 | [`toon`](https://github.com/toon-format/toon) | On-demand structured-data conversion | `toon "$INPUT_JSON" --stats -o "$OUTPUT_TOON"`; decode with `toon "$OUTPUT_TOON" --decode --strict -o "$RECOVERED_JSON"`; compare compact JSON |
 | [`ast-grep`](https://github.com/ast-grep/ast-grep) | On-demand structural source search | `ast-grep run --lang javascript --pattern 'function $NAME($$$ARGS) { $$$BODY }' --json=compact --stdin < "$SOURCE_FILE"` |
 | [`codebase-memory-mcp`](https://github.com/DeusData/codebase-memory-mcp) | On-demand native MCP/bridge static graph | `search_graph`, `trace_path`; use returned project/node IDs and original source |
 | [`context-hub`](https://github.com/andrewyng/context-hub) | On-demand curated documentation | `chub search "python pytest" --json`, then `chub get "$DOC_ID" --lang py` |
 | [`markitdown`](https://github.com/microsoft/markitdown) | On-demand selected document conversion | `markitdown "$INPUT_HTML" -o "$OUTPUT_MD"`; base installation does not include every PDF/Office extra |
-| [`mcporter`](https://github.com/openclaw/mcporter) | On-demand MCP CLI bridge with explicit config | `mcporter --config "$MCPORTER_CONFIG" list socraticode --brief --no-oauth`; a listing is not a successful search |
-| [`ccusage`](https://github.com/ccusage/ccusage) | On-demand native history accounting | `ccusage codex daily --offline --no-cost --json --timezone UTC --config /dev/null`; select the intended native home |
-| [`agentsview`](https://github.com/kenn-io/agentsview) | Optional selected-history archive/viewer | Configure allowed source directories before `agentsview sync`; query returned project ID; refresh explicitly |
+| [`mcporter`](https://github.com/openclaw/mcporter) | On-demand MCP CLI bridge with explicit config | `mcporter --config "$MCPORTER_CONFIG" list socraticode --brief --no-oauth`; a listing is not a successful search, and a successful call is transport acceptance, not a token saving |
+| [`ccusage`](https://github.com/ccusage/ccusage) | On-demand native history accounting | `ccusage codex daily --offline --no-cost --json --timezone UTC --config /dev/null`; select the intended native home; token-only while any model is unpriced ([recipe row](../recipes/README.md#component-catalog-install-and-check)) |
+| [`agentsview`](https://github.com/kenn-io/agentsview) | Optional selected-history archive/viewer | Configure allowed source directories before `agentsview sync`; query returned project ID; refresh explicitly; add `--include-children --include-automated --include-one-shot` for worker sessions ([history recipe](../recipes/README.md#history-and-usage)) |
 | [`claude-hud`](https://github.com/jarrodwatts/claude-hud) | Optional automatic Claude statusline after `/claude-hud:setup` | Inspect actual interactive Claude; not a Codex HUD or independent billing ledger |
 | [`otel-tui`](https://github.com/ymtdzzz/otel-tui) | On-demand local telemetry viewer | `otel-tui --host 127.0.0.1 --grpc 24317 --http 24318`; route only a selected producer to unused ports |
 | [`opentelemetry-collector-contrib`](https://github.com/open-telemetry/opentelemetry-collector-contrib) | Observation service, automatic only after configuration/start | `otelcol-contrib validate --config="$OTEL_CONFIG"`; verify actual event delivery separately |
@@ -225,7 +225,7 @@ Sources: [QMD MCP query/get](https://github.com/tobi/qmd/tree/v2.8.3), [this cat
 
 Use TOON for uniform arrays of flat records (same keys in every item); keep compact JSON for nested or non-uniform data, where TOON can be larger (upstream README).
 
-Sources: [TOON 4.1.1 README](https://github.com/toon-format/toon/blob/v4.1.1/packages/toon/README.md#when-not-to-use-toon) and [tabular encoder](https://github.com/toon-format/toon/blob/v4.1.1/packages/toon/src/encode/tabular.ts). The encoder accepts a non-empty uniform array; there is no five-record minimum.
+Sources: [TOON 4.1.1 README](https://github.com/toon-format/toon/blob/v4.1.1/packages/toon/README.md#when-not-to-use-toon) and [tabular encoder](https://github.com/toon-format/toon/blob/v4.1.1/packages/toon/src/encode/tabular.ts#L6-L78). There is no five-record minimum: the encoder writes a table for one or more non-empty objects that share one key set, whose columns hold primitives or, recursively, non-empty objects that share one key set, and falls back to list form for an empty object or an array-valued column ([known upstream limits](#known-upstream-limits-behind-the-lanes)).
 
 For large selected text, use headroom_compress, then headroom_retrieve for recovery; require fidelity and count the recovery cost.
 
@@ -239,6 +239,18 @@ Before claiming a task done, follow the installed verification-before-completion
 
 Already installed: [`skillOverrides` in `adoption/templates/claude.settings.template.json`](../adoption/templates/claude.settings.template.json) sets `verification-before-completion` to `on` and `search-first` to `name-only`. Both are adopted; this hook adds no skill dependency and changes neither setting.
 
+### Known upstream limits behind the lanes
+
+These routing rules, added 2026-09-27, stay outside the carrier text above. Each answers a limit that the pinned upstream source shows or a retained receipt recorded; the linked recipe rows hold the commands.
+
+- **QMD.** Over MCP at v2.8.3, `query` expands plain text with a model and reranks by default. For a lexical lane, pass `searches: [{"type": "lex", "query": "..."}]`, the named `collections` (an array), a small `limit` and `rerank: false`, then `get` a bounded range ([MCP tool parameters](https://github.com/tobi/qmd/blob/v2.8.3/README.md#mcp-tool-parameters)). The catalog index holds only the two us-equities collections, so adoption and new-machine questions, such as the release re-pin step, are answered by a bounded read of `adoption/update.md` ([Codex run correction](../evidence/artifacts/token-e2e-codex-20260926/README.md#correction-to-296)). Before a scheduled update, check that every collection root exists, and afterwards compare a returned passage with disk ([#989](https://github.com/tobi/qmd/issues/989), [#991](https://github.com/tobi/qmd/issues/991); [document recipe](../recipes/README.md#documents-and-selected-artifacts)).
+- **codebase-memory.** Index the selected repository explicitly. `trace_path` leaves out tests and resolver evidence by default ([v0.11.0 `trace_path` schema](https://github.com/DeusData/codebase-memory-mcp/blob/v0.11.0/src/mcp/mcp.c#L532-L560)), and `search_code` is a graph-ranked text search, so a literal hit can be a mention rather than a call ([`search_code` schema](https://github.com/DeusData/codebase-memory-mcp/blob/v0.11.0/src/mcp/mcp.c#L632-L659)). Before reporting a complete caller set, request `include_evidence` (and `include_tests` when tests count), keep edges below 0.5 as candidates and check each against the original source or Serena ([static code graph](../recipes/README.md#static-code-graph)).
+- **Repomix.** `--compress` drops a Python definition whose signature spans several lines, without notice ([v1.18.1 `PythonParseStrategy.ts` L81-86](https://github.com/yamadashy/repomix/blob/v1.18.1/src/core/treeSitter/parseStrategies/PythonParseStrategy.ts#L81-L86)); both E2E receipts lost `status_body`. Route exact-definition, signature and inventory tasks to an uncompressed pack or the original source, and count that recovery read.
+- **TOON.** The flat-record wording above and the preregistered five-row metric are local selection policy. 4.1.1 has no row minimum: it encodes an array as a table when its objects are non-empty and share one key set, and each column holds only primitives or, recursively, non-empty objects that share one key set. An empty object, or a column holding arrays, falls back to list form ([`tabular.ts` L6-78](https://github.com/toon-format/toon/blob/v4.1.1/packages/toon/src/encode/tabular.ts#L6-L78)). Choose by exact encoded size and a value-equal strict decode, and keep the original JSON otherwise: a root string that starts with U+FEFF does not survive a round trip (open [#339](https://github.com/toon-format/toon/issues/339)).
+- **Headroom.** Use it only when the compressed text keeps the facts the task needs. Report compression, the response envelope and any recovery separately, because a task that needs the full original pays for compression and full retrieval, which can exceed the original ([laptop run](../evidence/artifacts/token-e2e-ultracode-laptop-20260926/README.md#what-baseline_kind-means)). Through MCPorter, pass `--server` with `--name`, or a positional argument becomes the server selector ([MCPorter row](../recipes/README.md#component-catalog-install-and-check)).
+- **Serena and SocratiCode.** A passing Python fixture does not establish complete references in other languages or paths. In the laptop run, Serena's TypeScript server missed six of eight call sites of a function under `.claude/` until an explicit `.claude` include, because TypeScript's default include skips dot-directories; SocratiCode's semantic search skips dot-directories while `INCLUDE_DOT_FILES` is `false` ([laptop run](../evidence/artifacts/token-e2e-ultracode-laptop-20260926/README.md#retained-failures-and-gaps); [v1.14.0 Indexing Behaviour](https://github.com/giancarloerra/SocratiCode/blob/v1.14.0/README.md#indexing-behaviour)). Check project inclusion for the language and path before relying on a complete reference or search result, and read known excluded files directly.
+- **Context Hub, MarkItDown and ast-grep.** Check a curated document's `metadata.versions` before accepting it. Give MarkItDown the input type (`-x html`) when the extension is not the format's own, and qualify each optional extra a workload needs. Run ast-grep from a directory with no unreviewed `sgconfig.yml` above it, and check `outline` or YAML-rule tasks against the original source. The [component catalog](../recipes/README.md#component-catalog-install-and-check) rows carry the sources.
+
 ## Choose the new-PC profile and install once
 
 Clone [the canonical repository](https://github.com/seathatflowsinourveins/native-agent-stack), select a reviewed revision, and record `git rev-parse HEAD`. Read [adoption](../adoption/README.md), its [manifest](../adoption/manifest.json) and [update protocol](../adoption/update.md). Linux/WSL2 x86_64 is the accepted portability target; other hosts need matching assets and their own checks.
@@ -357,7 +369,7 @@ Keep the native default jCodeMunch ledger intact; historical custom-root account
 | --- | --- |
 | MCP command, environment, project root or server settings changed | In the app: **Settings → MCP servers → select the server → Restart**, then inspect `/mcp` and verify a useful call. This is the [official restart path](https://learn.chatgpt.com/docs/extend/mcp). |
 | Startup instructions or plugin/hook adoption changed | Start a new Codex task/session in the intended project/home and inspect the relevant instructions/hooks. If an existing task retains an old tool catalog, use a fresh task after the server restart. |
-| QMD documents changed | Run `qmd --index "$QMD_INDEX" update`; read the expected returned document. No client or PC restart is needed. |
+| QMD documents changed | Confirm each collection root exists, run `qmd --index "$QMD_INDEX" update`, then compare one returned passage with the file on disk: at 2.8.3 a missing root deactivates its documents and an emptied file keeps its old content ([limits](#known-upstream-limits-behind-the-lanes)). No client or PC restart is needed. |
 | Project language server/index changed | Restart only the selected server if needed, then check the language/index and exact source; avoid rebuilding unrelated indexes. |
 | Provider quota/auth error, shared counter mismatch or missing historical telemetry | Check the actual account/error or scope. Restarting cannot reset provider quota, separate shared ledgers, recover missing past events or prove savings. |