#262 [Feat] Importance-aware packing: rank files under a token budget (v5.2)

[Anonymous]

Originally created by: Avazbek22

Summary

Token-budget packing (#261) cuts the selection in deterministic order and reports what did not fit. That is the right default: predictable, and the agent stays in control of what matters via paths. But when the caller has no strong opinion about priorities, the budget is spent on whatever comes first in tree order — not on the files most likely to matter.

This issue adds an opt-in importance ranking: when a budget is set and ranking is requested, files are ordered by estimated importance before the cut, and the result explains the ordering instead of hiding it.

Ranking signals

Composable, cheap, offline signals — no ML, no embeddings, no network:

1. Code graph centrality. The Tree-sitter pipeline already parses sources for compression; build a file-level reference graph from it (imports/symbol references) and score files by centrality, so a file referenced across the codebase outranks a leaf nobody imports. Prior art for the approach: Aider's repo map (tree-sitter symbol graph + PageRank under a token budget).
2. Git activity. Files changed recently and often rank above files untouched for years. Read from local history only.
3. Path/type heuristics (smallest weight): sources above generated and vendored content.

Weights must be deterministic: the same repository state always produces the same ranking.

Transparency requirement

The product line is "no silent context loss", so ranking must be visible, not magical:

• Ranking is opt-in (e.g. rank: importance); the default stays deterministic selection order.
• The result reports which files made the cut and which did not, with a rank summary — enough for the caller to see why a file was excluded and override with paths if the ranking got it wrong.

Surfaces

• MCP: rank parameter on pack_context, meaningful together with max_tokens.
• CLI: --rank on export context, meaningful together with the budget option.
• GUI/TUI: not applicable — manual selection with live token metrics already expresses the user's own priorities.

Non-goals

• No machine learning, embeddings, or network calls.
• No change to the default behavior: without an explicit rank argument, budget cuts keep deterministic selection order.
• Ranking never overrides exclusion rules — ignored/excluded files stay excluded regardless of score.

Dependencies

• Builds on token-budget packing from [#261] (budget + honest cut report ship first).

Acceptance criteria

• Same repo state → same ranking (pinned by tests, including tie-breaking).
• Result contract documents the rank report; Docs/McpServer.md, CommandLine.md, and the CLI contract updated together with the implementation.
• A short evaluation note on 2-3 real repositories showing that top-ranked files are the obviously central ones — before any public claims about ranking quality.