230 lines
9.7 KiB
Markdown
230 lines
9.7 KiB
Markdown
# Spec: Layered Map Protocol
|
|
|
|
## Status
|
|
|
|
| Field | Value |
|
|
|---|---|
|
|
| Phase | **Spec** |
|
|
| Based on | [Proposal](proposal.md) |
|
|
| Next | Design |
|
|
|
|
## Overview
|
|
|
|
`pi-project-map` must move from a bulk-preload model to a layered navigation model. The system should always provide a small root protocol plus root index, selectively load likely relevant directory indexes first, load rich maps next for the strongest matches, and require source verification before edits or precise runtime claims.
|
|
|
|
## Decisions
|
|
|
|
| # | Question | Answer |
|
|
|---|---|---|
|
|
| 1 | Per-directory artifact model | Every non-ignored directory gets both `.pi-map.md` and `.pi-map.index.md` |
|
|
| 2 | Tier 0 default | Project Map Protocol + root `.pi-map.index.md` |
|
|
| 3 | Root rich map auto-read | Yes for architecture/system questions and ambiguous tasks |
|
|
| 4 | Retrieval style before query tool exists | Hybrid auto-load, indexes first |
|
|
| 5 | Backward compatibility with old preload-only model | Not required |
|
|
| 6 | Query-driven context bundling | Deferred to follow-up spec `map-context-retrieval` |
|
|
| 7 | Mode shape | Paired artifact mode is the only mode for now |
|
|
| 8 | Index section naming | Simple fixed names: `role`, `parent`, `children`, `files`, `links`, `workflows`, `dirty` |
|
|
| 9 | Rich map section naming | Current-plus fixed names: `role`, `files`, `arch`, `tags`, `symbols`, `workflows`, `dirty` |
|
|
| 10 | Patch-size override surface | Available from both CLI and tool surfaces |
|
|
| 11 | Structural classification output | Validation explains the main structural reason concisely |
|
|
| 12 | Extra retrieval backends | No vector store or Engram dependency in this change |
|
|
|
|
## Functional requirements
|
|
|
|
### 1. Paired artifacts per directory
|
|
Every non-ignored directory must generate two artifacts:
|
|
- `.pi-map.index.md` — quick-routing index
|
|
- `.pi-map.md` — rich orientation document
|
|
|
|
Both artifacts must share a common identity marker such as `dir: <relative-path>`.
|
|
|
|
### 2. Root entrypoint
|
|
The tool must generate a root navigation layer in both root artifacts.
|
|
|
|
#### Root Tier 0 behavior
|
|
Tier 0 must always include:
|
|
- Project Map Protocol
|
|
- root `.pi-map.index.md`
|
|
|
|
The generated root artifacts must explicitly state this behavior.
|
|
|
|
#### Root rich map behavior
|
|
Root `.pi-map.md` must:
|
|
- point to root `.pi-map.index.md` for traversal,
|
|
- restate the trust boundary,
|
|
- be suitable for automatic loading on architecture/system questions and ambiguous tasks.
|
|
|
|
### 3. Project Map Protocol
|
|
The generated system must define an explicit protocol with at least these rules:
|
|
1. Read the Project Map Protocol and root `.pi-map.index.md` first.
|
|
2. Use `index:` / `map:` references to open relevant directory indexes and maps.
|
|
3. Load indexes before rich maps during task-start navigation.
|
|
4. Read the local rich map and actual source before editing.
|
|
5. Treat non-empty `## dirty` sections in either artifact as stale.
|
|
6. If source and generated artifacts disagree, trust source.
|
|
7. If map and index disagree, trust neither blindly; verify from source and regenerate the pair.
|
|
8. After editing source, run `project_map_patch` for each changed file.
|
|
9. Before broad architectural claims or final handoff, run `project_map_validate` when freshness matters.
|
|
|
|
### 4. Index contract
|
|
Every `.pi-map.index.md` must use a fixed section order and remain optimized for fast routing.
|
|
|
|
#### Required behavior
|
|
- Keep architectural prose minimal.
|
|
- Omit uncertain workflow/file hints rather than labeling confidence.
|
|
- Allow up to 5 workflow hints by default, with configuration support.
|
|
- Do not include dependency edges in indexes.
|
|
- Include explicit parent link when a parent mapped directory exists.
|
|
- For child directory entries, point to both child `index:` and child `map:`.
|
|
- Leaf-directory indexes remain tiny but still follow the same contract.
|
|
|
|
#### Fixed section order
|
|
Each index must use this fixed order:
|
|
1. `## role`
|
|
2. `## parent`
|
|
3. `## children`
|
|
4. `## files`
|
|
5. `## links`
|
|
6. `## workflows`
|
|
7. `## dirty`
|
|
|
|
#### Minimum contents
|
|
Each index must minimally support:
|
|
- title header in the form `# <relative-path> (index)`
|
|
- `dir` identity marker
|
|
- short role summary
|
|
- parent link where applicable
|
|
- child directories where applicable
|
|
- likely files
|
|
- explicit sibling/child `index:` / `map:` links
|
|
- short workflow hints in hybrid task→route form
|
|
- `## dirty`
|
|
|
|
### 5. Rich map contract
|
|
Every `.pi-map.md` must use a fixed section order and remain optimized for dense orientation.
|
|
|
|
#### Required behavior
|
|
- Rich maps must explicitly link to their sibling `.pi-map.index.md`.
|
|
- Rich maps may keep some routing overlap, but indexes remain primary for navigation.
|
|
- `files` entries should be slightly richer than the current dense line format when useful.
|
|
- Tags should default to up to 8, with configuration support.
|
|
- Symbols should be prioritized for density in large directories using structural importance plus LLM refinement.
|
|
- Cross-repo workflow routing should live mostly in indexes, not maps.
|
|
|
|
#### Fixed section order
|
|
Each rich map must use this fixed order:
|
|
1. `## role`
|
|
2. `## files`
|
|
3. `## arch`
|
|
4. `## tags`
|
|
5. `## symbols`
|
|
6. `## workflows`
|
|
7. `## dirty`
|
|
|
|
#### Minimum contents
|
|
Each rich map must minimally support:
|
|
- title header in the form `# <relative-path>`
|
|
- `dir` identity marker
|
|
- sibling `index:` link near the top
|
|
- richer but still compact workflow guidance
|
|
- `## dirty`
|
|
|
|
### 6. Workflow generation
|
|
Workflow hints may be LLM-heavy, but they must be normalized into a deterministic schema before rendering.
|
|
|
|
#### Index workflow rules
|
|
- Primary form is hybrid task→route, for example: `change CLI behavior -> read: src/.pi-map.index.md, src/cli.ts`
|
|
- Cross-repo routing is allowed.
|
|
- Uncertain hints should be omitted.
|
|
- Indexes should optimize for fast routing, not standalone completeness.
|
|
|
|
### 7. Shared generation model
|
|
Map and index generation must come from a shared intermediate directory model rather than unrelated passes.
|
|
|
|
The renderer may present different views, but the underlying directory identity and source facts must stay aligned.
|
|
|
|
### 8. Patch behavior
|
|
`project_map_patch` must never manually edit generated artifacts; it must regenerate them.
|
|
|
|
#### Changed directory
|
|
For every changed source file, patch must update both artifacts for the changed directory.
|
|
|
|
#### Ancestor refresh behavior
|
|
Patch sizing must be auto-detected with an explicit override path available from both CLI and tool surfaces.
|
|
|
|
- **Small change default:** up to 3 closely related files and no structural/routing shift
|
|
- changed directory: refresh map + index
|
|
- ancestors: refresh indexes only
|
|
- **Large/structural change:** exports, directory shape, routing metadata, or broader cross-area impact
|
|
- changed directory: refresh map + index
|
|
- ancestors: refresh both map + index
|
|
|
|
### 9. Validation behavior
|
|
`project_map_validate` must hard-fail when paired artifacts are missing or structurally stale.
|
|
|
|
Validation output should prefer concise inline wording, for example:
|
|
- `[structural] src/foo.ts: export change`
|
|
- `[stale-index] src/.pi-map.index.md: likely files out of date`
|
|
|
|
Validation must check at least:
|
|
- missing `.pi-map.index.md` or `.pi-map.md`
|
|
- stale `## dirty` sections in either artifact
|
|
- broken `index:` / `map:` references
|
|
- stale `files:` pointers
|
|
- map/index pair disagreement on routing hints or referenced areas
|
|
- sibling pair identity mismatches
|
|
|
|
When validation classifies a patch as structural, it should report the main reason concisely, such as export change, directory-shape change, or routing impact.
|
|
|
|
#### Repair
|
|
Repair must be exposed through `project-map validate --fix`.
|
|
|
|
Default repair scope is the affected directory pair plus the necessary ancestor chain.
|
|
Repair summaries should also report the chosen `patchMode` concisely, for example: `repaired affected chain (patchMode: structural)`.
|
|
|
|
### 10. Visibility and policy
|
|
`.pi-map.index.md` must follow the same hidden/ignored policy as `.pi-map.md`.
|
|
|
|
Agents should never manually edit either artifact directly.
|
|
|
|
## Non-functional requirements
|
|
|
|
- Prefer density over completeness.
|
|
- Keep indexes routing-first and maps understanding-first.
|
|
- Keep the protocol simple enough to emit in root artifacts and prompt guidance.
|
|
- Support configuration for top-level `workflowHintCap` and `tagCap` keys.
|
|
- Do not require a vector store, Engram, or other extra retrieval backend for this design.
|
|
|
|
## User flows
|
|
|
|
### Flow 1: Agent starts work on a repo
|
|
1. Agent reads the Project Map Protocol and root `.pi-map.index.md`
|
|
2. For architecture/system or ambiguous tasks, agent also reads root `.pi-map.md`
|
|
3. Agent opens likely relevant directory indexes first
|
|
4. Agent opens the strongest-match rich maps
|
|
5. Agent reads source only when exact behavior or editing is involved
|
|
|
|
### Flow 2: Agent edits a file
|
|
1. Agent routes with index data
|
|
2. Agent reads the local rich map and actual source
|
|
3. Agent edits source
|
|
4. Agent runs `project_map_patch` for changed files
|
|
5. Patch refreshes the changed directory pair and the required ancestor chain
|
|
|
|
### Flow 3: Validation and repair
|
|
1. Agent runs `project_map_validate`
|
|
2. Missing/stale pair failures are reported as hard errors
|
|
3. Agent runs `project-map validate --fix` when repair is desired
|
|
4. The affected chain is regenerated
|
|
|
|
## Acceptance criteria
|
|
|
|
- [ ] Every non-ignored directory produces both `.pi-map.md` and `.pi-map.index.md`
|
|
- [ ] Tier 0 behavior is both documented and emitted in generated root artifacts
|
|
- [ ] Indexes have a fixed routing-first contract with parent/child/sibling links
|
|
- [ ] Rich maps have a fixed orientation-first contract with sibling index links
|
|
- [ ] `project_map_patch` refreshes both changed-directory artifacts and size-appropriate ancestor artifacts
|
|
- [ ] `project_map_validate` hard-fails on missing/stale paired artifacts and supports `--fix`
|
|
- [ ] Workflow-hint count and tag cap are configurable
|
|
- [ ] Prompt guidance expresses: index routes, map orients, source decides
|