# 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.