Implement layered maps and context retrieval
This commit is contained in:
@@ -0,0 +1,200 @@
|
||||
# Design: Layered Map Protocol
|
||||
|
||||
## Status
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Phase | **Design** |
|
||||
| Based on | [Spec](spec.md) |
|
||||
| Next | Tasks |
|
||||
|
||||
## Design summary
|
||||
|
||||
This change introduces a paired, navigation-first artifact model without changing the core mission of `pi-project-map`. The implementation should keep the existing discover → analyze → merge → render pipeline, but route both outputs through a shared intermediate directory model:
|
||||
|
||||
- `.pi-map.index.md` = routing-first view
|
||||
- `.pi-map.md` = orientation-first view
|
||||
|
||||
Source remains the final authority.
|
||||
|
||||
## Affected areas
|
||||
|
||||
### Source files likely to change
|
||||
- `src/format.ts`
|
||||
- `src/init.ts`
|
||||
- `src/patch.ts`
|
||||
- `src/validate.ts`
|
||||
- `pi-extension.ts`
|
||||
- `README.md`
|
||||
- `SKILL.md`
|
||||
- `design-doc.md`
|
||||
- CLI argument parsing for `validate --fix` if not already supported
|
||||
|
||||
### New modules likely to appear
|
||||
- `src/root-index.ts` or equivalent shared index generation helper
|
||||
- `src/directory-model.ts` or equivalent shared intermediate model helper
|
||||
- optional config support for workflow/tag caps if not already present in config handling
|
||||
|
||||
## Architecture changes
|
||||
|
||||
### 1. Shared intermediate model
|
||||
Build one structured directory model per mapped directory, then render two views from it.
|
||||
|
||||
The model should carry at least:
|
||||
- directory identity (`dir`)
|
||||
- sibling/parent/child relationships
|
||||
- likely files
|
||||
- role/arch summaries
|
||||
- tags
|
||||
- prioritized symbols
|
||||
- workflow candidates in normalized schema
|
||||
- stale/freshness markers
|
||||
|
||||
This shared model is the main guard against map/index drift.
|
||||
|
||||
### 2. Universal paired artifacts
|
||||
During init/reinit, generate both `.pi-map.md` and `.pi-map.index.md` for every non-ignored directory.
|
||||
|
||||
#### Index rendering target
|
||||
Indexes should be small and role-first, using this fixed order:
|
||||
- `# <relative-path> (index)`
|
||||
- `## role`
|
||||
- `## parent`
|
||||
- `## children`
|
||||
- `## files`
|
||||
- `## links`
|
||||
- `## workflows`
|
||||
- `## dirty`
|
||||
|
||||
Index content should include:
|
||||
- `dir`
|
||||
- short role summary
|
||||
- parent link
|
||||
- child directory links
|
||||
- likely files
|
||||
- explicit sibling/child `index:` / `map:` links
|
||||
- up to configured workflow hints
|
||||
- dirty marker
|
||||
|
||||
Indexes must omit dependency edges and keep architectural prose minimal.
|
||||
|
||||
#### Rich-map rendering target
|
||||
Maps should remain dense but richer, using this fixed order:
|
||||
- `# <relative-path>`
|
||||
- `## role`
|
||||
- `## files`
|
||||
- `## arch`
|
||||
- `## tags`
|
||||
- `## symbols`
|
||||
- `## workflows`
|
||||
- `## dirty`
|
||||
|
||||
Map content should include:
|
||||
- `dir`
|
||||
- sibling `index:` link near the top
|
||||
- slightly richer file lines than today when useful
|
||||
- prioritized symbol lists in large directories
|
||||
|
||||
### 3. Root artifact behavior
|
||||
Root `.pi-map.index.md` is the Tier 0 routing artifact.
|
||||
|
||||
Root `.pi-map.md` remains rich and must:
|
||||
- point to root index,
|
||||
- restate the trust boundary,
|
||||
- be suitable for automatic loading on architecture/system or ambiguous tasks.
|
||||
|
||||
Both root artifacts should explicitly encode the Tier 0 behavior.
|
||||
|
||||
### 4. Workflow synthesis
|
||||
Workflow hints may be LLM-heavy, but they must be normalized into a deterministic shape before rendering.
|
||||
|
||||
Suggested normalized fields:
|
||||
- `task`
|
||||
- `read`
|
||||
- `index`
|
||||
- `map`
|
||||
- optional `files`
|
||||
|
||||
Indexes should render workflow hints in compact task→route form.
|
||||
|
||||
Because the user wants cross-repo workflow routing allowed, workflow synthesis may target other directories outside the local subtree when the hints are strong.
|
||||
|
||||
### 5. Configuration
|
||||
Paired mode is the only mode for now, but these knobs should be configurable:
|
||||
- workflow-hint cap (default 5)
|
||||
- rich-map tag cap (default 8)
|
||||
|
||||
Configuration belongs in shared config handling rather than ad hoc generator constants.
|
||||
|
||||
Suggested config shape for v1:
|
||||
|
||||
```yaml
|
||||
workflowHintCap: 5
|
||||
tagCap: 8
|
||||
```
|
||||
|
||||
### 6. Patch behavior
|
||||
Patch should always regenerate, never hand-edit, generated artifacts.
|
||||
|
||||
#### Changed directory
|
||||
Always regenerate both the local `.pi-map.md` and `.pi-map.index.md`.
|
||||
|
||||
#### Ancestor strategy
|
||||
Use auto-detected patch sizing with explicit override available from both CLI and tool surfaces.
|
||||
|
||||
- **Small default:** up to 3 related files, no structure/routing shift
|
||||
- refresh ancestor indexes only
|
||||
- **Large/structural:** export changes, directory shape changes, routing metadata impact, or wider cross-area effect
|
||||
- refresh both ancestor indexes and ancestor maps
|
||||
|
||||
This suggests a helper that computes the affected chain and the required artifact depth for each ancestor.
|
||||
|
||||
### 7. Validation behavior
|
||||
Validation should become pair-aware, not just file-list-aware.
|
||||
|
||||
Checks should include:
|
||||
- missing sibling artifact
|
||||
- sibling `dir` mismatch
|
||||
- broken parent/child/sibling references
|
||||
- stale `dirty` markers
|
||||
- stale or missing likely-file references
|
||||
- disagreement between map/index routing references
|
||||
|
||||
Validation failures for missing/stale indexes are hard failures.
|
||||
|
||||
When validation classifies a patch as structural, the output should explain the main reason concisely (for example export change, directory-shape change, or routing impact).
|
||||
|
||||
Repair should be exposed through `validate --fix`, which regenerates the affected chain by default.
|
||||
|
||||
Validation and repair messaging should stay concise and inline, with the main structural reason plus the chosen `patchMode` when repair runs.
|
||||
|
||||
### 8. Prompt and doc integration
|
||||
`pi-extension.ts`, `SKILL.md`, and docs should explicitly teach:
|
||||
- Tier 0 = protocol + root index
|
||||
- indexes first, maps next
|
||||
- local rich map + source before edits
|
||||
- validate before freshness-sensitive handoff
|
||||
- `index routes, map orients, source decides`
|
||||
|
||||
### 9. External dependency boundary
|
||||
This design should stay self-contained.
|
||||
|
||||
- No vector store is required.
|
||||
- No Engram dependency is required.
|
||||
- Retrieval remains local, deterministic, and based on generated paired artifacts.
|
||||
|
||||
## Risks
|
||||
|
||||
| Risk | Mitigation |
|
||||
|---|---|
|
||||
| Pair generation increases implementation size | Keep a shared intermediate model and split delivery into slices |
|
||||
| Workflow hints become noisy | Omit uncertain hints and normalize schema before rendering |
|
||||
| Ancestor refresh logic becomes brittle | Centralize affected-chain computation and test small vs structural cases |
|
||||
| Pair drift creates false confidence | Use common `dir` identity and pair-aware validation |
|
||||
| Config knobs spread inconsistently | Keep workflow/tag caps in shared config loading |
|
||||
|
||||
## Settled v1 defaults
|
||||
|
||||
- Root `.pi-map.md` points to root `.pi-map.index.md` rather than repeating route summaries.
|
||||
- The shared intermediate directory model remains internal; behavior is tested through rendered outputs.
|
||||
- Validation surfaces structural reasons as concise inline messages.
|
||||
Reference in New Issue
Block a user