201 lines
6.4 KiB
Markdown
201 lines
6.4 KiB
Markdown
# 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.
|