127 lines
4.1 KiB
Markdown
127 lines
4.1 KiB
Markdown
# Spec: Map Context Retrieval
|
|
|
|
## Status
|
|
|
|
| Field | Value |
|
|
|---|---|
|
|
| Phase | **Spec** |
|
|
| Based on | [Proposal](proposal.md) |
|
|
| Next | Design |
|
|
|
|
## Overview
|
|
|
|
Add a retrieval-oriented `context` command that turns a user task into a compact project-map routing bundle. This change depends on the paired root/per-directory index+map metadata introduced by `layered-map-protocol`.
|
|
|
|
## Dependency
|
|
|
|
This change should not begin implementation before `layered-map-protocol` has landed enough metadata to support routing and ranking.
|
|
|
|
## Functional requirements
|
|
|
|
### 1. Tool-first surface
|
|
Pi should expose `project-map context` as a first-class tool action so agents can request a context bundle directly.
|
|
|
|
For v1, the tool input should be minimal:
|
|
- `query: string`
|
|
|
|
### 2. CLI follow-up surface
|
|
The CLI should support the same conceptual shape:
|
|
|
|
```bash
|
|
project-map context "<query>"
|
|
```
|
|
|
|
CLI support may follow after the tool contract is stable.
|
|
The CLI should mirror the same main input name: `query`.
|
|
### 3. Bundle contents
|
|
A context bundle must contain, at minimum:
|
|
- relevant indexes
|
|
- strongest-match relevant maps
|
|
- likely files
|
|
- relevant symbols when useful
|
|
- short next-step instructions
|
|
### 4. Ranking behavior
|
|
The command must rank candidates using generated metadata such as:
|
|
- root workflow hints
|
|
- directory index routing hints
|
|
- parent/child/sibling link structure
|
|
- package tags
|
|
- symbol references
|
|
- task/workflow entries
|
|
- `files:` / `index:` / `map:` targets
|
|
|
|
Indexes should be the first routing layer. Rich maps and symbols should expand from the strongest routed candidates.
|
|
|
|
By default, retrieval should usually surface the top 3 candidate directories, with adaptive omission of weaker rich maps when confidence drops.
|
|
### 5. Trust boundary
|
|
The bundle must instruct the agent to:
|
|
- read indexes first for orientation,
|
|
- read rich maps next when deeper context is needed,
|
|
- read source before editing or asserting exact behavior.
|
|
|
|
## Output shape
|
|
|
|
The first version should be markdown-first, with stable, schema-like sections optimized for LLM consumption rather than human prose.
|
|
|
|
Default section order:
|
|
1. `query`
|
|
2. `relevant indexes`
|
|
3. `relevant maps`
|
|
4. `likely files`
|
|
5. `relevant symbols`
|
|
6. `instructions`
|
|
|
|
The retrieval title format should remain retrieval-specific:
|
|
- `# Context bundle: <query>`
|
|
|
|
A representative response shape:
|
|
|
|
```markdown
|
|
# Context bundle: validation stale signatures
|
|
|
|
## query
|
|
validation stale signatures
|
|
|
|
## relevant indexes
|
|
- .pi-map.index.md
|
|
- src/.pi-map.index.md
|
|
- tests/.pi-map.index.md
|
|
|
|
## relevant maps
|
|
- src/.pi-map.md
|
|
- tests/.pi-map.md
|
|
|
|
## likely files
|
|
- src/validate.ts
|
|
- src/ast/ast-extract.ts
|
|
- tests/validate.test.ts
|
|
|
|
## relevant symbols
|
|
- validateMaps
|
|
- generateDirectoryMap
|
|
- extractFileAST
|
|
|
|
## instructions
|
|
Read the indexes first, then the strongest-match rich maps, then verify behavior from source before editing.
|
|
```
|
|
|
|
The tool should omit weak/unhelpful symbol output rather than forcing a noisy symbol section.
|
|
## Non-functional requirements
|
|
|
|
- Output must be compact enough for prompt injection.
|
|
- Ranking should be deterministic enough to test.
|
|
- The implementation should prefer lightweight heuristics over heavyweight indexing.
|
|
- Retrieval should reuse the paired-artifact parsing layer instead of ad hoc string slicing.
|
|
- Retrieval should not require a vector store, Engram, or another external memory backend.
|
|
- The first version should accept natural language queries first; structured filters can come later.
|
|
- Candidate explanations are not required by default.
|
|
- Result-count override and root-rich-map inclusion can come later if needed, but are not part of v1.
|
|
## Acceptance criteria
|
|
|
|
- [ ] Pi exposes `project-map context <query>` as a tool-first surface
|
|
- [ ] CLI support follows the same shape after the tool contract is stable
|
|
- [ ] Retrieval output includes indexes, strongest-match maps, files, and instructions
|
|
- [ ] Symbol hints appear only when paired metadata makes them useful
|
|
- [ ] Ranking respects the index-first routing model and usually returns top 3 candidates
|
|
- [ ] Docs show when to use the retrieval command
|
|
- [ ] Trust-boundary guidance remains explicit |