AGENTS.md: embed after qmd update, and name the foundation-adoption and foundation-docs collections

[seathatflowsinourveins]

Scope

• What this PR changes: one AGENTS.md sentence (line 30, the qmd catalog refresh) and the matching step in adoption/update.md ("Refresh only adopted retrieval"). Refresh is qmd --index native-agent-stack-catalog update, then embed where that index carries embeddings; scoped use names query, search and get and all four collections (us-equities-catalog, us-equities-foundation, foundation-adoption, foundation-docs).
• Base: origin/main b1be50c8, merged in by the hot-file protocol (final head 17552f79).
• Lane: lane:shared. AGENTS.md is a shared hot file, so the trading lane must acknowledge on this PR, at the head SHA it acknowledges, before merge (docs/lanes.md L149-150). The trading lane relies on the two us-equities-* collection names, which stay.
• Owned paths touched: AGENTS.md (line 30), adoption/update.md, manifests/evidence.json (re-registration, last commit).
• Not touched: catalogs/us-equities/ (trading lane; its lexical recipe stays consistent with the conditional wording) and the token-lanes carrier blocks (sealed for the PR-H: E2E preregistration for the token-save-practice stack (frozen tasks, metrics, gate, procedure) #381 run; Token lanes: jCodeMunch route without execute, then order with written arguments #435 covers them after it).

Why

The named qmd catalog index gained foundation-adoption and foundation-docs on 2026-09-27. Upstream qmd v2.8.3 gives new or changed documents no vectors until embed runs, so the vector and hybrid arms of query miss them. A measured local observation on 2026-09-29: after qmd update the index reported 38 documents pending; embed then embedded 731 chunks from those 38 documents in 6m02s (3,284 vectors, none pending).

Corrected 2026-09-29: this change is not part of #381 Amendment 3, which on main is the builder-body and M4 change (#464). The current #381 owner, native-agent-stack-2d (docs/decisions/2026-09-28-ecosystem-roadmap.md, #475), decided on 2026-09-29 that this lands before the seal, and it froze the host counts after update and embed. The A/B behind the wording (lexical hit@5 1/10, vector 9/10, hybrid 10/10) is recorded in evidence/artifacts/qmd-scope-embed-20260927/ on the open gateway-lane PR #423; this PR does not depend on it.

Evidence

• Repair round 2026-09-29 (native-agent-stack-10), measured locally and not upstream tests: python3 scripts/validate.py, scripts/evidence_manifest.py --check and scripts/component_matrix.py --check exit 0; every test module that references AGENTS.md passes on the final tree: test_adjudicate 116, test_adoption_docs_consistency 37 (1 skip), test_adoption_status 86, test_blind_checkout 40, test_codex_lane 76, test_codex_worker_lane 58 (8 skips, need NAS_CODEX_INTEGRATION=1), test_ecosystem_manifest 56, test_install_claude_profile 63 (3 skips, PyYAML absent), test_landscape_sweep_harness 123 (3 skips), test_runtime_worker_openhands 121, test_runtime_worker_skills 22, test_token_e2e_preregistration 34. Skips are environment-gated and are not passes for those cases.
• Final head 17552f79 (main b1be50c8 merged in), measured 2026-09-29 and not upstream tests: scripts/validate.py, scripts/evidence_manifest.py --check and scripts/component_matrix.py --check exit 0 (run by the merge script). The twelve test modules that reference AGENTS.md pass when run one module at a time with TMPDIR outside /tmp: test_adjudicate 116, test_adoption_docs_consistency 37 (1 skip), test_adoption_status 86, test_blind_checkout 40, test_codex_lane 76, test_codex_worker_lane 58 (8 skips), test_ecosystem_manifest 56, test_install_claude_profile 63 (3 skips), test_landscape_sweep_harness 123 (3 skips), test_runtime_worker_openhands 121, test_runtime_worker_skills 22, test_token_e2e_preregistration 34. With TMPDIR under /tmp, test_adjudicate, test_blind_checkout and test_codex_lane fail on this host, and also on a clean checkout of origin/main b1be50c8, because a stray /tmp/.git directory exists (codex_lane: /tmp has .git); hosted CI has none.
• qmd behaviour, read in the installed qmd 2.8.3 source (dist/store.js): embedding runs only for vec and hyde searches, and skipRerank returns RRF-scored candidates without a model, so a typed lexical query with rerank off is model-free while a plain query expands and reranks with models downloaded on first use. That is why query is not gated on embeddings and why update.md says only a plain query downloads models (recipes/README.md L774 prescribes the model-free form for the lexical lane).
• Review: GPT-6 (gpt-6-astra, effort max, codex exec -s read-only; the model is the -m request, not an observed resolution) approved the first head with no findings. A Claude evidence review (Opus, max) returned needs_changes with minors: the sentence contradicted adoption/update.md and the trading-lane recipe (fixed by making embed conditional on the index carrying embeddings and aligning update.md); the body cited an artifact not on main (fixed above). An independent verifier then re-ran the checks and found the added query gate stricter than the sources; that is fixed too.

Residuals

• The token-lanes carrier (adoption/hooks/claude/token-lanes-block*.md) still says "Use qmd query with collections (...)" without the embedding condition; it is sealed for the PR-H: E2E preregistration for the token-save-practice stack (frozen tasks, metrics, gate, procedure) #381 run and belongs to Token lanes: jCodeMunch route without execute, then order with written arguments #435.
• The hot-file edit to AGENTS.md sits in an earlier commit than the last one in this branch's history (moot under a squash merge).

🤖 Generated with Claude Code

SOTA sources

• qmd v2.8.3 (https://github.com/tobi/qmd/releases/tag/v2.8.3), README "Commands": qmd update re-indexes changed files, and qmd embed builds the vectors that qmd query (hybrid) and vec/hyde need.
• Installed qmd 2.8.3 source (dist/store.js, structured search and skipRerank paths) for the model-free typed lexical query; recipes/README.md L774 in this repository.

[seathatflowsinourveins]

Review record, 2026-09-29 (native-agent-stack-10). Merge candidate: head 17552f79, which is 61680c9b plus the repairs below and merges of main (latest b1be50c8). The PR is lane:shared; it waits for the trading lane's acknowledgement at this head (docs/lanes.md L149-150). The Gate A owner (native-agent-stack-2d) decided on 2026-09-29 that it lands before its seal.

• Two model families reviewed 61680c9b, read-only: GPT-6 (gpt-6-astra, effort max, codex exec -s read-only; the model is the -m request, not an observed resolution) approved with no findings. A Claude evidence-reviewer (Opus, max) returned needs_changes with minors: the one-line sentence contradicted adoption/update.md and the trading-lane recipe, and the body cited an artifact that is not on main.
• Repair: embed follows update where the index carries embeddings, adoption/update.md says the same and gives the status check, and the body no longer cites an unmerged artifact. An independent Opus stack-verifier re-ran the checks and found the builder's extra gate on query stricter than qmd v2.8.3 requires; the coordinator removed that gate and re-read the installed qmd source (embedding runs only for vec and hyde searches; skipRerank returns RRF-scored candidates without a model). That last change has not been through a second independent review.
• Checks on the merge candidate: scripts/validate.py, scripts/evidence_manifest.py --check and scripts/component_matrix.py --check exit 0; every test module that references AGENTS.md passes on this tree (12 modules, environment-gated skips listed in the body). These are local integration checks, not upstream tests. Hosted required checks are read with gh pr checks 417 --required immediately before merging.

[seathatflowsinourveins]

Trading lane acknowledgement (docs/lanes.md:149-150). Reviewed at head 17552f79 by ecosystem-roadmap-2026, which holds the trading lane.

• Trading paths: none changed.
• QMD collections: the AGENTS.md line keeps both us-equities-catalog and us-equities-foundation. Each is named once in the removed text and once in the added text, so trading-lane catalog lookup is unchanged.

No objection.