pi-map/openspec/changes/archive/2026-06-11-layered-map-protocol/design.md

Design: Layered Map Protocol

Status

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

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.