Add semantic directory orientation

[sting8k]

Summary

• Public port of semantic directory orientation from premium, without harness docs/private-only material.
• Keep exact directory reads as listings, but route agents to semantic orientation with overview --scope <dir> --symbols and discover <symbol> --scope <dir> footers.
• Make overview --symbols emit budget-adaptive inline symbol anchors (kind name@line-range) and fall back top3 -> top2 -> compact names under the existing 15k hard cap.
• Align directory size labels with overview/file-glob style: header says sizes ~= tokens; rows use compact ~N values instead of repeating (N tokens).

Validation

• git diff --cached --check
• cargo fmt --check
• cargo test --locked --test map_output
• cargo test --locked --test path_exact
• cargo clippy --locked -- -D warnings
• cargo test --locked
• Smoke: srcwalk src/read and srcwalk overview --scope src/read --symbols

Release note

No version bump, tag, release, npm publish, or crates publish in this PR.

[greptile-apps]

Greptile Summary

This PR ports semantic directory orientation from a premium build: overview --symbols now emits budget-adaptive kind name@line-range anchors (falling back Anchored/3 → Anchored/2 → Compact to stay under the 15k token cap), and bare directory reads gain semantic next-step footers pointing agents at overview --scope --symbols and discover --scope. Token size labels in both directory listings and the overview tree are aligned to the compact ~N style.

• src/map.rs — extract_symbol_names replaced by extract_symbol_previews (kind + name + range), a new SymbolRenderMode enum drives three rendering passes, and format_overview_base is extracted to keep the fallback cascade readable.
• src/read/directory.rs — header updated to sizes ~= tokens, per-file suffix changed from (N tokens) to ~N, two NextAction::guidance footers appended.
• Tests — map_symbols_includes_symbol_names updated for the new anchor format; directory_path_read_routes_to_semantic_overview added to cover the footer and label changes end-to-end.

Confidence Score: 5/5

Safe to merge — the changes are well-scoped to output formatting and the fallback cascade is correctly bounded by the existing 15k token hard cap.

The budget-adaptive fallback cascade correctly exhausts all render modes before surfacing an error, the symbol preview parsing correctly strips the range bracket before kind-matching, and the directory footer additions are purely additive. Integration tests cover the new anchor format and the directory listing changes end-to-end.

No files require special attention.

Important Files Changed

Filename	Overview
src/map.rs	Refactors symbol extraction into SymbolPreview structs (kind + name + range) and introduces a budget-adaptive fallback cascade: Anchored/3 → Anchored/2 → Compact. Logic is correct and the fallback correctly handles the relations-degradation path.
src/read/directory.rs	Adds semantic orientation footers (overview --scope --symbols, discover --scope) to directory listings and aligns token label format to ~N. Correct and consistent with the map.rs style.
tests/map_output.rs	Updates map_symbols_includes_symbol_names assertion to the new fn alpha@1, fn beta@2 anchored format. Coverage is sufficient for the changed behavior.
tests/path_exact.rs	Adds directory_path_read_routes_to_semantic_overview integration test covering the new footer, header format, and --symbols / discover hints in directory listings.
skills/srcwalk/GUIDE.md	Documents the --symbols fallback behavior inline; accurate and minimal.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["overview --symbols called"] --> B["generate_at_depth"]
    B --> C["extract_symbol_previews per file\n(kind + name + range)"]
    C --> D["symbol_modes = [Anchored/3, Anchored/2, Compact]"]
    D --> E["Loop: format_overview_base with mode"]
    E --> F{"enforce_hard_cap\n<= 15k tokens?"}
    F -- Yes --> G["Return output"]
    F -- No --> H{"More modes?"}
    H -- Yes --> E
    H -- No --> I{"Has relations?"}
    I -- Yes --> J["Degraded loop:\nformat without relations,\ncycle through modes"]
    J --> K{"enforce_hard_cap?"}
    K -- Yes --> G
    K -- No --> L["Error: output too large"]
    I -- No --> L

    M["srcwalk read dir"] --> N["list_directory"]
    N --> O["Header: sizes ~= tokens\nEntries: ~N per file"]
    O --> P["Next-action footers:\noverview --scope DIR --symbols\ndiscover symbol --scope DIR"]

Loading

_{Reviews (2): Last reviewed commit: "feat: add semantic directory orientation" | Re-trigger Greptile}