[scodge-24]

Stages 1-4 of the agentic-search incorporation plan plus the productized outcome of the
benchmark campaign (evidence trail: slice-cli-benchmark stage1-bench-and-index, FINDINGS.md).

• Stage 1: deps --files collaborator-file discovery + bidirectional depends-on:/blast-radius: context affordances.
• Stage 2: outline/symbols orientation surfaces (the one addition the loop A/Bs validated).
• Stage 3: Tree-sitter AST span backend behind --features ast (correctness upgrade; off by default).
• Stage 4: semantic embedding index + find --semantic behind --features semantic, code/cards/code-sliceaug unit modes.
• slice locate: the benchmark-validated composite discovery path as one command — semantic top hits as read-ready file:line anchors + a deterministic card-match disagreement CHECK (embedding misses are confidently wrong, never low-scored). Cross-model validated: 100% adoption at call 1 on three model families.
• Docs pass: README/setup/navigating/agent-workflows aligned with the new surface; slice-codebase skill now rebuilds the semantic index after reslicing.

Tests: 64 lib + 52 CLI pass; fmt + clippy -D warnings clean on both feature sets.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR expands slice-cli’s navigation surfaces to be more “actionable for agents”: it can now resolve dependency blast radius into concrete files (deps --files), advertises dependency context in context’s human output, and introduces additional opt-in retrieval/structure features (Tree-sitter symbol spans via ast, and embedding-based semantic search via semantic).

Changes:

• Add deps --files to emit dependency slices’ collaborator files (and conditionally serialize them in JSON).
• Add symbol-orientation commands (outline, symbols) with declared coverage; introduce an opt-in Tree-sitter AST backend (ast) to improve span precision.
• Add opt-in semantic indexing/query (semantic-index, find --semantic) plus supporting docs/design updates.

Reviewed changes

Copilot reviewed 14 out of 17 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
rust/slice-rs/tests/cli.rs	Adds/updates CLI tests covering deps --files, context affordances, and symbol surfaces (incl. feature-gated AST behavior).
rust/slice-rs/src/symbols.rs	Adds AST dispatch + symbol enumeration API while preserving heuristic fallback behavior.
rust/slice-rs/src/symbols_ast.rs	Introduces Tree-sitter backend for Python symbol spans under ast feature.
rust/slice-rs/src/semantic.rs	Adds semantic indexing + querying implementation under semantic feature.
rust/slice-rs/src/models.rs	Extends JSON models (DepsOutput.files) and adds symbol-output structs.
rust/slice-rs/src/lib.rs	Wires new feature-gated modules (semantic, symbols_ast).
rust/slice-rs/src/error.rs	Adds Embedding error variant under semantic feature.
rust/slice-rs/src/commands.rs	Implements deps --files, outline, symbols, and new context human affordance lines.
rust/slice-rs/src/cli.rs	Adds new CLI commands/flags and feature-gated semantic options.
rust/slice-rs/Cargo.toml	Introduces ast + semantic features and optional deps (tree-sitter*, ureq).
rust/slice-rs/Cargo.lock	Locks new optional dependency graph for ast/semantic.
docs/navigating.md	Documents deps --files and semantic search usage.
docs/agent-workflows.md	Documents context affordance behavior for agent workflows.
design/slice-cli-feature-map.md	Adds feature map snapshot describing current surfaces and feature gating.
design/idealised-paths.md	Adds analysis doc on “ideal paths” and routing detractors (snapshot).
.gitignore	Attempts to ignore generated semantic index artifacts.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[greptile-apps]

Greptile Summary

This PR incorporates Stages 1–4 of the agentic-search plan into slice-cli, plus the productized slice locate command. The changes add collaborator-file discovery (deps --files, blast-radius/depends-on affordances in context), symbol-orientation surfaces (outline/symbols), an opt-in Tree-sitter AST backend (--features ast), and a full semantic embedding index + composite discovery path (--features semantic).

• Stage 1–2: deps gains --files to resolve dependency slices to concrete files; context human output advertises both forward and reverse transitive file counts as actionable command hints; new outline/symbols commands enumerate confidently-spanned symbol definitions with declared coverage.
• Stage 3 (symbols_ast.rs): Tree-sitter Python backend drops in behind symbols.rs's three span operations under the ast feature; the heuristic remains the zero-dep default.
• Stage 4 + locate (semantic.rs): ~1 000-line new module — embedding index build, cosine candidate generation, deterministic re-ranking, find --semantic, and slice locate (semantic top-k + card-description cross-check). Both new feature flags are off by default, preserving the shipped binary's zero-heavy-dep invariant.

Confidence Score: 5/5

Safe to merge — all new surfaces are behind opt-in feature flags or additive to existing commands, and the default binary is unchanged.

All new functionality is gated behind the ast and semantic Cargo features (off by default), the JSON contracts for pre-existing commands are provably unchanged (regression test included), and the heuristic fallback is preserved for all symbol operations. The two findings are non-correctness issues under normal usage.

No files require special attention for merge safety. semantic.rs would benefit from a second pass when a local/offline embedder is added, particularly around the ranked_hits/locate API boundary.

Important Files Changed

Filename	Overview
rust/slice-rs/src/semantic.rs	New ~1000-line semantic module: embedding build, cosine candidate generation, deterministic re-rank, find --semantic, and slice locate; well-tested, though locate loads slice docs twice and cosine silently truncates on dimension mismatch.
rust/slice-rs/src/commands.rs	Adds outline, symbols, and deps --files handlers plus blast-radius/depends-on affordances to context; logic is correct and backed by new CLI-level tests.
rust/slice-rs/src/symbols_ast.rs	New Tree-sitter AST backend for Python symbol spans; recursive tree walk is correct and terminates, with well-targeted tests covering decorated/nested/multiline cases the heuristic rejects.
rust/slice-rs/src/symbols.rs	Adds enumerate_symbols + heuristic backend; cleanly separates heuristic from AST dispatch; existing tests pinned to heuristic impls, new tests cover the declared-coverage contract.
rust/slice-rs/src/cli.rs	Wires Outline, Symbols, Locate, SemanticIndex variants and extends Deps/Find; #[cfg(feature = "semantic")] guards correctly applied at both the variant and the match-arm level.
rust/slice-rs/src/models.rs	Adds CollaboratorFile, SymbolRow, SymbolsOutput; DepsOutput.files uses skip_serializing_if to keep default JSON byte-identical for existing consumers.
rust/slice-rs/Cargo.toml	Adds ast and semantic optional feature flags with correctly scoped optional dependencies; default feature set remains empty.
rust/slice-rs/tests/cli.rs	New CLI-level tests for deps --files (dedup, glob expansion, additive JSON), context affordance lines, outline, and symbols; regression guards for unchanged JSON contracts.

Sequence Diagram

sequenceDiagram
    participant Agent
    participant CLI as slice CLI
    participant Semantic as semantic.rs
    participant Commands as commands.rs
    participant Index as SEMANTIC.json
    participant OR as OpenRouter API
    participant Slices as slices/*.md

    Note over Agent,Slices: slice locate (composite discovery path)
    Agent->>CLI: slice locate "how does auth work"
    CLI->>Semantic: locate(ctx, needle, json, styles, top)
    Semantic->>Index: "load_index(Code) -> SemanticIndex"
    Semantic->>OR: "embed_query(needle) -> qvec"
    Semantic->>Slices: load_slice_docs() [inside ranked_hits]
    Semantic->>Semantic: "cosine candidates -> deterministic re-rank"
    Semantic->>Slices: load_slice_docs() [again for card_match]
    Semantic->>Semantic: "card_match(docs, needle) -> disagreement check"
    Semantic-->>Agent: file:line anchors + optional CHECK warning

    Note over Agent,Slices: slice deps --files (blast-radius discovery)
    Agent->>CLI: slice deps auth --reverse --transitive --files
    CLI->>Commands: "deps(ctx, auth, reverse=true, transitive=true, files=true)"
    Commands->>Slices: load_slice_docs_meta()
    Commands->>Commands: "transitive_reverse_deps() -> dep ids (BFS order)"
    Commands->>Commands: "collaborator_files() -> expand globs, dedup, attribute"
    Commands-->>Agent: file TAB slice_id rows (nearest collaborator first)

    Note over Agent,Slices: slice outline / symbols (orientation surface)
    Agent->>CLI: slice outline src/auth.py
    CLI->>Commands: outline(ctx, file)
    Commands->>Commands: enumerate_symbols() [AST or heuristic]
    Commands-->>Agent: file:start-end TAB name + coverage N/M

Loading

_{Reviews (7): Last reviewed commit: "fix: expand glob files: entries in deps ..." | Re-trigger Greptile}

[scodge-24]

@greptile review

[scodge-24]

@greptile review

[scodge-24]

@greptile review