Implement layered maps and context retrieval

2026-06-11 12:56:18 +02:00
parent 010e4b83eb
commit c6064f8d94
35 changed files with 4410 additions and 383 deletions
@@ -0,0 +1,75 @@
+# Tasks: Layered Map Protocol
+
+## Status
+
+| Field | Value |
+|---|---|
+| Phase | **Tasks** |
+| Based on | [Design](design.md) |
+| 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
+
+## 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.