Bound relation output: paginate list_relations, cap get_document relations and the cascade advisory

[ivklgn]

Summary

Relation data sent to the agent has no size limit. This breaks .archcore/code-quality/bounded-and-deterministic-output.rule.md: clause 1 (an MCP tool response and session context must be bounded by a named constant), clause 3 (order before cutting), and clause 6 (the ceiling is stated in the contract the caller reads).

The issue is real at current scale. In this repository, an unfiltered list_relations returns 41.9 KB for 326 relations, about 10–12K tokens. That already exceeds the budget list_documents protects.

Write-path performance moved to #33. Graph-shape analysis and the needs-design items stay in .archcore/mcp/relation-write-path-graph-growth.idea.md.

Current behavior (v0.8.3)

• list_relations with no path returns m.Relations in full, with no cap and no truncated flag (internal/mcp/tools/list_relations.go:40-41).
• m.Relations is in insertion order, not sorted, so a cut would not be deterministic.
• get_document returns all incoming and outgoing relations with no cap (internal/mcp/tools/get_document.go:79-91).
• The post-tool-use cascade advisory lists every incoming dependent with no cap (cmd/hook_post_tool_use.go:96-104). This is session context.
• list_documents already implements the pattern: listDefaultLimit = 100, listMaxLimit = 500, clamped limit, errors on negative limit or offset, an envelope struct, and the ceiling stated in the tool description (internal/mcp/tools/list_documents.go:15-68).

Scope

• list_relations: add limit and offset, and return {relations, total, offset, returned, truncated}, mirroring list_documents. Use named constants with a doc comment that names the budget.
• list_relations: sort by (source, target, type) before cutting. Apply the same cap when path is set.
• list_relations: state the ceiling and the envelope in the tool description.
• get_document: cap the incoming and outgoing relation lists with a named constant, and report truncation. State it in the tool description.
• Cascade advisory: cap the listed dependents with a named constant, and add a "+N more" line.
• Update internal/mcp/tools/list_relations_test.go. It decodes into map[string][]sync.Relation and breaks once the envelope has non-array fields. Add table-driven cases for the cap, the offset, and the ordering.
• Plugin repository: update the "full relation graph" wording in the archcore-auditor and archcore-assistant agents to describe pagination.

Files: internal/mcp/tools/list_relations.go, internal/mcp/tools/get_document.go, cmd/hook_post_tool_use.go (+ tests)

Acceptance: no relation output reaches the agent without a named ceiling. Cut results are deterministic. Each ceiling is visible in the tool description or the advisory text.

[ivklgn]

Narrowed after re-checking against v0.8.3.

• Both code findings hold. The original write-path analysis is preserved in this issue's edit history and in .archcore/mcp/relation-write-path-graph-growth.idea.md.
• Write-path work moved to Benchmark the relation write path before optimizing it #33, benchmarks first. Preliminary numbers show the save dominates and key-set dedup would not help, so that item is dropped. Batch add_relations is decided there from the numbers.
• Added two outputs with the same rule violation: get_document relation lists and the cascade advisory.
• Deriving same-folder links from the tree and the clique/degree advisory stay in the idea document as needs-design.