`--limit` bounds the ranked seed set but not the response

Class: incorrect · Severity: blocking Flow: arch-f220a644d654 · Step: graph expansion after ranking Question: issue-8bcb6b7f8308 · Frequency: every context call against a corpus with relations

Finding¶

--limit bounds the ranked seed set but not the response. One-hop graph expansion runs afterwards and appends neighbours with no cap.

What happens today¶

OBSERVED. Three decisions each with two outgoing edges: docir context "cache invalidation policy" --limit 3 returned 9 documents. Worst case is limit × (1 + max out-degree).

Impact¶

Directly negates the product's headline claim. docir exists to be "token-cheap for agents" (README:46); context is the flagship command; its default limit is 5; and the caller has no way to bound what comes back. On a well-linked corpus — the corpus docir is built to encourage — the overrun grows with graph density, so the tool degrades exactly as it is adopted successfully.

Proposed default¶

Apply limit to the final result, or add a separate explicit budget for graph-expanded neighbours (e.g. --expand N, default 0 or 1) and document the interaction.

Resolution¶

FIXED 2026-07-26. --limit is now a hard ceiling on the response and graph expansion runs inside it: --expand N (default 2) reserves at most N slots for neighbours, expansion is breadth-first across seeds so one dense hit cannot spend the whole budget, and slots the graph does not use are backfilled with more ranked hits — so a result is always min(limit, what exists). expand is clamped below limit, so a seed can never be crowded out. Verified by replaying PROBE-5 against the real CLI: --limit 3 now returns 3 (was 9), --expand 0 disables the graph, --limit 1 returns 1 ranked hit. Pinned by TestContextBudget in tests/modules/documents/test_integration_documents.py, confirmed to FAIL (assert 9 == 3) against the reverted implementation.

Actors affected¶

• AI coding agent

Evidence¶

• src/docir/modules/documents/application/services/document_service.py:260-273
• src/docir/modules/documents/application/services/document_service.py:297-307
• ref-1509d5dbb4c3 (discovery probe log)

---

Migrated from the discovery gap register (GAP-005); the register itself now lives in this store.