pi-map/openspec/changes/map-context-retrieval/spec.md

Spec: Map Context Retrieval

Status

Field	Value
Phase	Spec
Based on	Proposal
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:

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:

# 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