Token-lanes carrier: qmd query names the four collections, then a line window - #421

Summary

The SubagentStart token-lanes carrier and its handbook mirror now pass all four QMD collections explicitly: foundation-docs, foundation-adoption, us-equities-foundation and us-equities-catalog. They follow query with a bounded get window.

The reason: a QMD MCP server reads its default collection list once, when it is created, and a query without collections searches only that list (qmd v2.8.3 src/mcp/server.ts L189, L355). A long-running server therefore misses collections added later unless the query names them.

The block measures 4,094 UTF-8 bytes, inside the unchanged 4,100-byte bound. The portable QMD setup now creates the two foundation collections.

Changes

• adoption/hooks/claude/token-lanes-block.md and its SHA256SUMS line: the QMD line now reads "Use qmd query with collections (…four names…), then get a line window."
  • The window follows the query tool's own recipe, get(file, fromLine = max(1, line - 20), maxLines = 80, lineNumbers = true) (L257; get parameters at L412-413).
  • It is a bounded read, not a lossless transform. Line numbers stay on for file:line citations.
• docs/token-session-handbook.md: the mirrored line, with a sources line that cites the schema lines.
• catalogs/us-equities/native-workflows.md: collection add commands for foundation-adoption and foundation-docs. collection add has no ignore option, so the page also documents the YAML ignore: ["ecosystem/**"] that keeps the generated guide out.
• adoption/update.md: a one-time step for hosts that adopted the index before 2026-09-27.
• docs/decisions/2026-09-27-token-lanes-subagent-start.md: a dated addendum covering the need, a live MCP result, the byte split, rejected alternatives, the overturn condition and the PR-H: E2E preregistration for the token-save-practice stack (frozen tasks, metrics, gate, procedure) #381 hash freeze.
• tests/test_token_lanes_subagent_start.py: the measured-bytes comment. The 4,100 bound and the UTF-8 control keep their main values.
• manifests/evidence.json and generated reports: the hot-file registration, in the last commit (docs/lanes.md).

Evidence

• Live MCP result, 2026-09-27.
  • The call: a lexical query with collections: ["foundation-adoption"] and rerank: false, through this workstation's QMD MCP server.
  • That server started before the new collections existed; its start-up instructions list 2 collections and 121 documents.
  • It returned foundation-adoption/update.md as the top hit.
• Host index at build time: qmd --index native-agent-stack-catalog status reports 268 documents in 4 collections and 2,250 embedded vectors.
• Local integration at head 77b8357 on main 364f4d9:
  • tests.test_token_lanes_subagent_start: 14 tests OK.
  • validate.sh: FAILS=0.
  • Full suite: 6,661 tests OK, 762 skipped (TMPDIR outside the repository).

Review

An independent Opus evidence review of the unmerged first build returned repair.

The review's open questions:

• G1, acceptance at the rebased head: rerun above.
• G3, whether a running server reaches new collections: answered by the live MCP result.

SOTA sources

• tobi/qmd v2.8.3, the version installed on this host:
  • src/mcp/server.ts L189: the default collection list is read once, at server creation.
  • L355: a query without collections searches that list only.
  • L257: the query tool's own get window recipe. L330 and L412-413: the query and get parameters.
  • The installed 2.8.3 package README, L755: collections.<name>.ignore holds glob patterns excluded from indexing and is "YAML-only — no CLI command sets this" (README).
• The carrier contract this change stays inside:
  • docs/decisions/2026-09-27-token-lanes-subagent-start.md: the SubagentStart block and its 4,100-byte bound;
  • the PR-H: E2E preregistration for the token-save-practice stack (frozen tasks, metrics, gate, procedure) #381 preregistration's carrier-hash freeze.

Residuals

• AGENTS.md (a shared hot file) still names only the two us-equities collections for catalog lookup. AGENTS.md: embed after qmd update, and name the foundation-adoption and foundation-docs collections #417 (lane:shared) updates that line; this PR leaves it to AGENTS.md: embed after qmd update, and name the foundation-adoption and foundation-docs collections #417.
• No child run with the new block is claimed. PR-H: E2E preregistration for the token-save-practice stack (frozen tasks, metrics, gate, procedure) #381 freezes carrier hashes at execution, so its run records the installed hash.
• Installing on this host (install_claude_profile.py --only guard) follows the merge.

🤖 Generated with Claude Code