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

Tasks: Layered Map Protocol

Status

Field	Value
Phase	Tasks
Based on	Design
Next	Apply

Delivery slices

Slice 1: Shared model and paired rendering

Scope: shared intermediate directory model, universal paired artifacts, fixed section names/order, root Tier 0 entrypoint Review goal: establish the core paired architecture without retrieval-command work

Tasks:

1. Add a shared intermediate directory model for paired map/index generation
2. Extend render/parse support for paired .pi-map.md and .pi-map.index.md outputs with the agreed fixed section names/order
3. Add generation support for .pi-map.index.md in every non-ignored directory
4. Enrich root artifacts with explicit Tier 0 behavior and sibling links
5. Add/update tests for map/index rendering, fixed order, and sibling identity

Slice 2: Routing metadata and workflow normalization

Scope: likely files, parent/child/sibling links, workflow schema, rich-map metadata density rules Review goal: make the navigation model operational on real output

Tasks:

1. Add index-first routing metadata generation from AST/structure + LLM judgment
2. Normalize workflow hints into a deterministic schema before rendering
3. Add parent/child/sibling index: / map: references
4. Implement rich-map density rules for slightly richer file lines, tag cap, and prioritized symbols
5. Add/update tests for routing hints, leaf indexes, and workflow omission on low confidence

Slice 3: Patch sizing, cascade refresh, and repair

Scope: changed-directory pair refresh, ancestor-chain refresh rules, validation hard failures, validate --fix Review goal: make freshness and repair trustworthy

Tasks:

1. Make project_map_patch always regenerate both artifacts for the changed directory
2. Add auto-detected small vs structural patch sizing with explicit override in both CLI and tool surfaces
3. Refresh ancestor indexes for small changes and ancestor map+index pairs for structural changes
4. Expand validation for pair-aware checks, hard failures on missing/stale indexes, and concise structural-reason output
5. Add/confirm project-map validate --fix repair flow for affected-chain regeneration
6. Add/update tests for patch classification, ancestor refresh, and repair behavior

Slice 4: Prompt guidance, config knobs, and docs

Scope: Project Map Protocol, Tier 0 runtime guidance, workflow/tag config, docs rewrite Review goal: align runtime behavior and documentation with the final operating model

Tasks:

1. Update pi-extension.ts prompt guidance to teach the layered paired protocol
2. Update SKILL.md to describe indexes as routing and maps as orientation
3. Update README.md and design-doc.md consumption guidance
4. Add config support for workflow-hint cap and rich-map tag cap
5. Keep the paired-artifact model self-contained with no vector-store or Engram dependency
6. Add/update tests for config-driven caps and root Tier 0 guidance

Acceptance checklist

• Every non-ignored directory has both .pi-map.md and .pi-map.index.md
• Root Tier 0 behavior is emitted in generated root artifacts
• Indexes are routing-first, role-first, and include parent/child/sibling links
• Rich maps are orientation-first and include sibling index links
• Changed-directory patch always regenerates both artifacts
• Ancestor refresh follows small vs structural rules
• Validation hard-fails on missing/stale paired artifacts and supports validate --fix
• Workflow-hint count and tag cap are configurable
• No vector-store or Engram dependency is introduced
• npm run typecheck passes
• npm test passes
• npm run lint passes (N/A: repo has no ESLint config; pre-existing repository gap, not a change regression)

Review workload note

This change crosses format, generation, patching, validation, config, docs, and prompt guidance. Keep implementation in narrow, reviewable slices and avoid one oversized PR.