alex/pi-map
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

spec(openspec): archive completed project-map changes

Browse Source
This commit is contained in:
Alex
2026-06-12 10:06:30 +02:00
parent 11365fa4ed
commit 842dcc6235
24 changed files with 183 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files
openspec/changes/archive/2026-06-11-layered-map-protocol/apply-progress.md
+10
View File
@@ -0,0 +1,10 @@
# Apply Progress
Status: complete
Summary: Implemented paired map/index artifacts, layered routing/orientation protocol, pair-aware patch/validate/reinit flows, config caps, and docs/runtime guidance.
Implemented commits:
- c6064f8 Implement layered maps and context retrieval
Stale-checkbox reconciliation: historical implementation completed in committed work above; tasks.md reconciled to checked state on 2026-06-11.
openspec/changes/archive/2026-06-11-layered-map-protocol/archive-report.md
+9
View File
@@ -0,0 +1,9 @@
# Archive Report
Status: archived
Archived path: openspec/changes/archive/2026-06-11-layered-map-protocol
Archive mode: manual archive fallback in openspec-only repo with legacy flat change specs; canonical sync marked not-applicable in sync-report.md.
Inputs preserved in archive: proposal.md, spec.md, design.md, tasks.md, apply-progress.md, verify-report.md, sync-report.md.
openspec/changes/archive/2026-06-11-layered-map-protocol/design.md
+200
View File
@@ -0,0 +1,200 @@
# 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.
openspec/changes/archive/2026-06-11-layered-map-protocol/proposal.md
+96
View File
@@ -0,0 +1,96 @@
# Proposal: Layered Map Protocol
## Status
| Field | Value |
|---|---|
| Phase | **Proposal** |
| Based on | User interview + current design doc |
| Next | Spec |
## Problem
The current design centers consumption on discovering all `.pi-map.md` files and loading them at session start, with pruning for larger repositories. That scales poorly and frames maps as bulk context instead of as a navigation system.
The repo currently lacks:
1. a clear root routing artifact,
2. an explicit trust/use protocol,
3. a layered loading model,
4. fast per-directory navigation artifacts,
5. a clean split between routing metadata and richer orientation metadata.
## Proposed change
Adopt a layered navigation model built around a **paired artifact** for every non-ignored directory:
- `.pi-map.index.md` → fast routing
- `.pi-map.md` → richer orientation
### Tier model
- **Tier 0 — always injected:** Project Map Protocol + root `.pi-map.index.md`
- **Tier 1 — task-start load:** likely relevant directory indexes first, then rich maps for strongest matches
- **Tier 2 — exact verification:** source files, tests, configs, and docs
### Paired artifacts per directory
Every non-ignored directory should generate both:
- a rich `.pi-map.md`
- a lightweight `.pi-map.index.md`
The index is for movement. The map is for understanding. Source remains the final authority.
This change stays self-contained: it does not add a vector store, Engram dependency, or other external memory/retrieval backend.
### Operating model
- Root `.pi-map.md` remains rich, but points to root `.pi-map.index.md` for traversal.
- Each index points to its sibling rich map.
- Each rich map points back to its sibling index.
- If map and index disagree, trust neither blindly; verify from source and regenerate the pair.
## In scope
- [ ] Generate `.pi-map.index.md` for every non-ignored directory
- [ ] Keep `.pi-map.md` as the richer sibling artifact for every non-ignored directory
- [ ] Emit a Project Map Protocol in docs/prompt guidance and in generated root artifacts
- [ ] Replace eager "read all maps" guidance with layered retrieval guidance
- [ ] Define fixed index/map responsibilities and section order
- [ ] Cascade freshness and repair logic across changed directory pairs and affected ancestors
- [ ] Add strict validation for missing/stale/broken index-map pairs
- [ ] Update docs and skill guidance to reflect the new model
## Out of scope
- [ ] Add a query-driven retrieval command such as `project-map context <query>`
- [ ] Preserve backward compatibility for agents that only understand the old preload-only model
- [ ] Replace source verification with map-based authority
- [ ] Redesign the core AST/LLM extraction pipeline beyond what is needed to feed the new artifacts
## Decisions from grilling
| Topic | Decision |
|---|---|
| Change split | Two specs |
| This change slug | `layered-map-protocol` |
| Follow-up change slug | `map-context-retrieval` |
| Backward compatibility required | No |
| Artifact model | Every non-ignored directory gets both `.pi-map.md` and `.pi-map.index.md` |
| Root Tier 0 | Project Map Protocol + root `.pi-map.index.md` |
| Root rich map | Auto-read for architecture/system questions and ambiguous tasks |
| Root relationship | Root map points to root index |
| Retrieval mode | Hybrid auto-load, indexes first |
| Patch strategy | Changed dir updates both; ancestors refresh by size/structure rules |
| Validation | Hard-fail on missing/stale indexes, repair via `validate --fix` |
| Prompt trust boundary | index routes, map orients, source decides |
| Extra retrieval backends | None in this change |
| SDD mode | Interactive |
| Artifact store | OpenSpec |
| PR strategy | Auto-forecast |
| Review budget | 400 lines |
## Success criteria
- [ ] Every non-ignored directory has both a fast index and a richer map
- [ ] The root artifacts clearly tell an agent how to navigate and when to read source
- [ ] The documented consumption model no longer requires reading every `.pi-map.md` up front
- [ ] Validation fails on stale or missing paired artifacts and offers a repair path
- [ ] Patch/refresh behavior keeps routing trustworthy without requiring full reinit for small changes
openspec/changes/archive/2026-06-11-layered-map-protocol/spec.md
+229
View File
@@ -0,0 +1,229 @@
# 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
openspec/changes/archive/2026-06-11-layered-map-protocol/sync-report.md
+7
View File
@@ -0,0 +1,7 @@
# Sync Report
Status: NOT-APPLICABLE
Reason: This repository uses legacy flat change artifacts (proposal.md/spec.md/design.md/tasks.md) and does not maintain a canonical openspec/specs/ tree for these changes. No canonical spec sync was performed.
User-approved fallback: archive completed change as an audit record without canonical spec sync.
openspec/changes/archive/2026-06-11-layered-map-protocol/tasks.md
+75
View File
@@ -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
- [x] Every non-ignored directory has both `.pi-map.md` and `.pi-map.index.md`
- [x] Root Tier 0 behavior is emitted in generated root artifacts
- [x] Indexes are routing-first, role-first, and include parent/child/sibling links
- [x] Rich maps are orientation-first and include sibling index links
- [x] Changed-directory patch always regenerates both artifacts
- [x] Ancestor refresh follows small vs structural rules
- [x] Validation hard-fails on missing/stale paired artifacts and supports `validate --fix`
- [x] Workflow-hint count and tag cap are configurable
- [x] No vector-store or Engram dependency is introduced
- [x] `npm run typecheck` passes
- [x] `npm test` passes
- [x] `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.
openspec/changes/archive/2026-06-11-layered-map-protocol/verify-report.md
+22
View File
@@ -0,0 +1,22 @@
# Verify Report
Status: PASS
Change: layered-map-protocol
Verified summary: Implemented paired map/index artifacts, layered routing/orientation protocol, pair-aware patch/validate/reinit flows, config caps, and docs/runtime guidance.
Evidence commands:
- npm run typecheck
- npx vitest run
- npm run build
- node dist/cli.js validate .
Current validation state:
- npm run typecheck: PASS
- npx vitest run: PASS (262/262)
- npm run build: PASS
- node dist/cli.js validate .: PASS
Notes:
- Repo-wide lint remains unavailable because the repository has no ESLint config; treated as a pre-existing repository-level gap, not a change regression.
openspec/changes/archive/2026-06-11-map-context-retrieval/apply-progress.md
+10
View File
@@ -0,0 +1,10 @@
# Apply Progress
Status: complete
Summary: Implemented deterministic index-first context retrieval via tool and CLI, plus retrieval docs/skill guidance.
Implemented commits:
- c6064f8 Implement layered maps and context retrieval
Stale-checkbox reconciliation: historical implementation completed in committed work above; tasks.md reconciled to checked state on 2026-06-11.
openspec/changes/archive/2026-06-11-map-context-retrieval/archive-report.md
+9
View File
@@ -0,0 +1,9 @@
# Archive Report
Status: archived
Archived path: openspec/changes/archive/2026-06-11-map-context-retrieval
Archive mode: manual archive fallback in openspec-only repo with legacy flat change specs; canonical sync marked not-applicable in sync-report.md.
Inputs preserved in archive: proposal.md, spec.md, design.md, tasks.md, apply-progress.md, verify-report.md, sync-report.md.
openspec/changes/archive/2026-06-11-map-context-retrieval/design.md
+65
View File
@@ -0,0 +1,65 @@
# Design: Map Context Retrieval
## Status
| Field | Value |
|---|---|
| Phase | **Design** |
| Based on | [Spec](spec.md) |
| Next | Tasks |
## Design summary
This change adds a lightweight retrieval layer on top of paired project-map metadata. It should not require a new external storage system, vector store, or Engram dependency. Instead, it should scan root and directory indexes first, expand to rich maps and files from the strongest candidates, and emit an agent-friendly bundle.
## Likely implementation areas
- `pi-extension.ts` for the first-class tool surface
- `src/index.ts` for exports
- new retrieval module, e.g. `src/context.ts` or `src/retrieve.ts`
- shared parsing/model code from the layered protocol
- `src/cli/*` for follow-up CLI wiring
- docs and skill guidance
## Retrieval pipeline
1. Accept a natural-language `query`
2. Read root `.pi-map.index.md` and, when needed, root `.pi-map.md`
3. Parse paired index/map metadata through the shared format/model layer
4. Score candidate directories primarily from indexes
5. Keep the top 3 candidates by default
6. Expand strongest candidates to rich maps, likely files, and symbols
7. Emit a compact markdown bundle with stable section order and retrieval-specific title `# Context bundle: <query>`
## Candidate scoring inputs
- direct term matches in workflow hints
- direct term matches in likely files
- parent/child/sibling link context
- direct term matches in tags
- direct term matches in symbols
- path/name similarity
- root workflow routing hits
A first implementation can use deterministic weighted lexical scoring.
Candidate-selection reasoning does not need to be exposed by default.
## Parsing strategy
Reuse the paired-artifact parser/model from the layered protocol. Avoid retrieval-specific ad hoc parsing.
## Risks
| Risk | Mitigation |
|---|---|
| Retrieval becomes too fuzzy to trust | Keep output advisory and always direct agent back to source |
| Pair parser complexity grows | Extend shared format/model logic instead of command-local parsing |
| Command output becomes too large | Limit result count and keep instructions terse |
## Open choices
1. Exact scoring weights for workflow hints vs files vs tags vs symbols
2. Whether the tool should support optional structured output later
3. Whether broad architecture queries should be allowed to exceed the usual top-3 default in a later version
4. Whether later versions should support optional root-rich-map inclusion as a flag
openspec/changes/archive/2026-06-11-map-context-retrieval/proposal.md
+53
View File
@@ -0,0 +1,53 @@
# Proposal: Map Context Retrieval
## Status
| Field | Value |
|---|---|
| Phase | **Proposal** |
| Based on | Follow-up to `layered-map-protocol` |
| Next | Spec |
## Problem
After the layered map protocol lands, the agent will know it should load root protocol + root index first, then route through per-directory indexes and rich maps. But the repo will still lack an ergonomic retrieval primitive that can turn a natural-language task into a compact context bundle.
Without that helper, the agent still has to manually inspect directory indexes, rank candidate areas, and expand to rich maps/files. That weakens the value of the new routing layer.
## Proposed change
Add a retrieval tool and command shape:
```bash
project-map context "<user task>"
```
The first-class surface should be a Pi tool. CLI support can follow the same shape.
The retrieval result should return a compact context bundle containing:
- relevant indexes,
- strongest-match rich maps,
- likely source files,
- relevant symbols when useful,
- short instructions on what to read next.
This remains a local metadata-driven retrieval feature, not a vector-store or Engram-backed memory system.
## In scope
- [ ] Add Pi tool support for `project-map context <query>`
- [ ] Add CLI support using the same shape after the tool contract is stable
- [ ] Rank results using paired index/map metadata from the layered protocol
- [ ] Return a compact, markdown-first, agent-friendly context bundle
- [ ] Document recommended usage from prompts and docs
## Out of scope
- [ ] Full semantic search across arbitrary source contents
- [ ] Replacing source verification with map-based answers
- [ ] Building a heavyweight external indexer or vector database
## Success criteria
- [ ] A natural-language task can resolve to likely indexes/maps/files/symbols without manual repo scanning
- [ ] Output is compact enough to inject directly into the next step
- [ ] Retrieval builds on generated paired metadata rather than bypassing it
- [ ] The first version is tool-first and markdown-first
openspec/changes/archive/2026-06-11-map-context-retrieval/spec.md
+127
View File
@@ -0,0 +1,127 @@
# Spec: Map Context Retrieval
## Status
| Field | Value |
|---|---|
| Phase | **Spec** |
| Based on | [Proposal](proposal.md) |
| Next | Design |
## Overview
Add a retrieval-oriented `context` command that turns a user task into a compact project-map routing bundle. This change depends on the paired root/per-directory index+map metadata introduced by `layered-map-protocol`.
## Dependency
This change should not begin implementation before `layered-map-protocol` has landed enough metadata to support routing and ranking.
## Functional requirements
### 1. Tool-first surface
Pi should expose `project-map context` as a first-class tool action so agents can request a context bundle directly.
For v1, the tool input should be minimal:
- `query: string`
### 2. CLI follow-up surface
The CLI should support the same conceptual shape:
```bash
project-map context "<query>"
```
CLI support may follow after the tool contract is stable.
The CLI should mirror the same main input name: `query`.
### 3. Bundle contents
A context bundle must contain, at minimum:
- relevant indexes
- strongest-match relevant maps
- likely files
- relevant symbols when useful
- short next-step instructions
### 4. Ranking behavior
The command must rank candidates using generated metadata such as:
- root workflow hints
- directory index routing hints
- parent/child/sibling link structure
- package tags
- symbol references
- task/workflow entries
- `files:` / `index:` / `map:` targets
Indexes should be the first routing layer. Rich maps and symbols should expand from the strongest routed candidates.
By default, retrieval should usually surface the top 3 candidate directories, with adaptive omission of weaker rich maps when confidence drops.
### 5. Trust boundary
The bundle must instruct the agent to:
- read indexes first for orientation,
- read rich maps next when deeper context is needed,
- read source before editing or asserting exact behavior.
## Output shape
The first version should be markdown-first, with stable, schema-like sections optimized for LLM consumption rather than human prose.
Default section order:
1. `query`
2. `relevant indexes`
3. `relevant maps`
4. `likely files`
5. `relevant symbols`
6. `instructions`
The retrieval title format should remain retrieval-specific:
- `# Context bundle: <query>`
A representative response shape:
```markdown
# Context bundle: validation stale signatures
## query
validation stale signatures
## relevant indexes
- .pi-map.index.md
- src/.pi-map.index.md
- tests/.pi-map.index.md
## relevant maps
- src/.pi-map.md
- tests/.pi-map.md
## likely files
- src/validate.ts
- src/ast/ast-extract.ts
- tests/validate.test.ts
## relevant symbols
- validateMaps
- generateDirectoryMap
- extractFileAST
## instructions
Read the indexes first, then the strongest-match rich maps, then verify behavior from source before editing.
```
The tool should omit weak/unhelpful symbol output rather than forcing a noisy symbol section.
## Non-functional requirements
- Output must be compact enough for prompt injection.
- Ranking should be deterministic enough to test.
- The implementation should prefer lightweight heuristics over heavyweight indexing.
- Retrieval should reuse the paired-artifact parsing layer instead of ad hoc string slicing.
- Retrieval should not require a vector store, Engram, or another external memory backend.
- The first version should accept natural language queries first; structured filters can come later.
- Candidate explanations are not required by default.
- Result-count override and root-rich-map inclusion can come later if needed, but are not part of v1.
## Acceptance criteria
- [ ] Pi exposes `project-map context <query>` as a tool-first surface
- [ ] CLI support follows the same shape after the tool contract is stable
- [ ] Retrieval output includes indexes, strongest-match maps, files, and instructions
- [ ] Symbol hints appear only when paired metadata makes them useful
- [ ] Ranking respects the index-first routing model and usually returns top 3 candidates
- [ ] Docs show when to use the retrieval command
- [ ] Trust-boundary guidance remains explicit
openspec/changes/archive/2026-06-11-map-context-retrieval/sync-report.md
+7
View File
@@ -0,0 +1,7 @@
# Sync Report
Status: NOT-APPLICABLE
Reason: This repository uses legacy flat change artifacts (proposal.md/spec.md/design.md/tasks.md) and does not maintain a canonical openspec/specs/ tree for these changes. No canonical spec sync was performed.
User-approved fallback: archive completed change as an audit record without canonical spec sync.
openspec/changes/archive/2026-06-11-map-context-retrieval/tasks.md
+34
View File
@@ -0,0 +1,34 @@
# Tasks: Map Context Retrieval
## Status
| Field | Value |
|---|---|
| Phase | **Tasks** |
| Based on | [Design](design.md) |
| Next | Apply |
## Tasks
1. [ ] Add Pi tool support for `project-map context` with `query` as the main input
2. [ ] Add retrieval module for scoring paired index/map metadata
3. [ ] Reuse or extend shared paired-artifact parsing/model code
4. [ ] Rank candidate directories from indexes first, then expand to maps/files/symbols
5. [ ] Emit compact markdown-first context bundles with stable section order and retrieval-specific `Context bundle` title
6. [ ] Add tests for retrieval ranking, top-3 default behavior, and output shape
7. [ ] Add CLI support after the tool contract is stable
8. [ ] Update docs and skill guidance for retrieval usage
## Acceptance checklist
- [x] Tool works for natural-language queries via `query`
- [x] Output includes relevant indexes, strongest-match maps, likely files, symbols when useful, and instructions
- [x] Retrieval depends on paired metadata rather than raw source scanning
- [x] Ranking follows the index-first routing model with a top-3 default
- [x] `npm run typecheck` passes
- [x] `npm test` passes
- [x] `npm run lint` passes *(N/A: repo has no ESLint config; pre-existing repository gap, not a change regression)*
## Sequencing note
This change is intentionally follow-up work. It should start after the layered map protocol produces reliable paired routing metadata.
The first delivery surface is the Pi tool. CLI support follows the stabilized tool contract.
openspec/changes/archive/2026-06-11-map-context-retrieval/verify-report.md
+23
View File
@@ -0,0 +1,23 @@
# Verify Report
Status: PASS
Change: map-context-retrieval
Verified summary: Implemented deterministic index-first context retrieval via tool and CLI, plus retrieval docs/skill guidance.
Evidence commands:
- npm run typecheck
- npx vitest run
- npm run build
- node dist/cli.js context "validation routing"
- node dist/cli.js validate .
Current validation state:
- npm run typecheck: PASS
- npx vitest run: PASS (262/262)
- npm run build: PASS
- node dist/cli.js validate .: PASS
Notes:
- Repo-wide lint remains unavailable because the repository has no ESLint config; treated as a pre-existing repository-level gap, not a change regression.
openspec/changes/archive/2026-06-11-project-map-prompt-injection/apply-progress.md
+15
View File
@@ -0,0 +1,15 @@
# Apply Progress
Status: complete
Summary: Implemented prompt-injection slices 1-5: mode/config surface, root-pair preload, reinjection/dedupe, strict/advisory/strong/off semantics, and documentation/runtime alignment.
Implemented commits:
- 56560d9 feat(prompt): implement prompt injection slice 1
- 621434b feat(prompt): implement prompt injection slice 2
- 19666c9 feat(prompt): implement prompt injection slice 3
- 58e8bd3 feat(prompt): implement prompt injection slice 4
- 11365fa docs(prompt): align prompt injection guidance and runtime copy
- c11d49d spec(prompt): add project map prompt injection change set
Stale-checkbox reconciliation: historical implementation completed in committed work above; tasks.md reconciled to checked state on 2026-06-11.
openspec/changes/archive/2026-06-11-project-map-prompt-injection/archive-report.md
+9
View File
@@ -0,0 +1,9 @@
# Archive Report
Status: archived
Archived path: openspec/changes/archive/2026-06-11-project-map-prompt-injection
Archive mode: manual archive fallback in openspec-only repo with legacy flat change specs; canonical sync marked not-applicable in sync-report.md.
Inputs preserved in archive: proposal.md, spec.md, design.md, tasks.md, apply-progress.md, verify-report.md, sync-report.md.
openspec/changes/archive/2026-06-11-project-map-prompt-injection/design.md
+235
View File
@@ -0,0 +1,235 @@
# Design: Project Map Prompt Injection
## Status
| Field | Value |
|---|---|
| Phase | **Design** |
| Based on | [Spec](spec.md) |
| Next | Tasks |
## Design summary
This change adds a runtime guidance layer on top of the paired map/index artifact system. The implementation should not redesign map generation or retrieval. Instead, it should add a well-scoped injection pipeline that:
- emits honest startup hints before init,
- preloads the root pair after init,
- expands under a hybrid budget,
- avoids redundant reinjection by scanning real outgoing context,
- varies guidance strength through explicit modes,
- proves correctness with integration-heavy validation.
## Affected areas
### Source files likely to change
- `pi-extension.ts`
- shared config handling (`src/config.ts` or equivalent)
- runtime helpers for map/index discovery and injection selection
- tests covering extension lifecycle and per-turn behavior
- docs/runtime guidance surfaces if needed
### New modules likely to appear
- `src/prompt-injection.ts` or equivalent runtime helper
- optional helper for canonical marker construction / detection
- optional helper for token-budget estimation across paired artifacts
## Architecture changes
### 1. Injection policy helper
Centralize prompt-injection logic in one helper rather than scattering it across hooks.
Suggested responsibilities:
- determine current mode (`off` / `advisory` / `strong` / `strict`),
- detect whether artifacts exist,
- build pre-init startup hint,
- build post-init root-pair payload,
- estimate expansion budget,
- choose additional artifacts under the budget,
- construct a canonical injected marker/block,
- scan outgoing context or payload for that marker,
- decide whether reinjection is required.
This helper is the main guard against drift between startup hints, context hooks, and strict-mode checks.
### 2. Injection surfaces
Use different extension surfaces for different responsibilities.
#### Pre-init / startup hint
Use `before_agent_start` for lightweight startup guidance before real artifacts exist.
Required behavior:
- inject only a hint,
- tell the agent to run `project_map_init`,
- keep the hint visible and inspectable.
#### Post-init root-pair preload
Use `before_agent_start` to guarantee the initial post-init root-pair preload for a prompt.
Required behavior:
- inject root `.pi-map.index.md`,
- inject root `.pi-map.md`,
- optionally append brief protocol text only if needed by the selected mode.
#### Relevant-turn reinjection
Use `context` for relevant-turn checks.
Required behavior:
- inspect `event.messages`,
- decide whether the canonical block is already present,
- only add the root pair / budgeted expansion if absent,
- avoid rescanning on every trivial turn in `strong` mode.
#### Payload fallback
Use `before_provider_request` only as a fallback or debugging surface when message-layer detection is insufficient.
### 3. Canonical marker design
Deduplication depends on stable canonical detection.
The implementation should stamp injected content with a canonical marker block.
Recommended v1 shape:
- a deterministic wrapper such as `<!-- PI_MAP_ROOT_PAIR_START -->` / `<!-- PI_MAP_ROOT_PAIR_END -->`,
- normalized artifact identity lines for root `.pi-map.index.md` and root `.pi-map.md`,
- trust-boundary text within the same wrapped block when the active mode requires it.
Marker rules:
- stable across turns,
- independent of provider formatting quirks,
- easy to scan in both `event.messages` and final provider payload,
- robust enough that root-pair presence can be detected without brittle full-text matching.
### 4. Budgeting
Budgeting should be deterministic and layered.
#### Context-window discovery and fallback
- Prefer active-model context-window metadata exposed by Pi runtime/model selection.
- If context-window metadata is unavailable, fall back to the configured absolute cap.
- The fallback path should be explicit in logs/debug behavior so budget decisions remain auditable.
#### Required order
1. compute effective budget from relative percentage + optional absolute cap,
2. reserve the root pair first,
3. expand outward using a deterministic traversal order,
4. stop when the budget would be exceeded.
#### Traversal strategy
The spec does not force exact traversal heuristics, but the design should prefer:
- root pair first,
- shallow structural coverage before deep leaves,
- predictable order over opaque scoring.
This keeps automatic injection understandable and auditable.
### 5. Mode control surface
Expose a config/runtime setting for the four modes.
Because the current project config is loaded from flat JSON in `.pi-project-map.json`, v1 should prefer a flat compatible shape rather than forcing an immediate nested/YAML migration.
Suggested v1 config shape:
```json
{
"promptInjectionMode": "strong",
"contextBudgetPercent": 15,
"contextBudgetMaxTokens": 100000
}
```
Migration note:
- keep existing flat JSON loading in `src/config.ts`,
- treat these as new additive keys,
- decide explicitly whether existing `contextBudget` is deprecated, ignored for injection, or retained only for older LLM-analysis paths.
Optional runtime UX may later mirror thinking-level controls, but v1 implementation can start with config-driven mode selection as long as the semantics are the same.
### 6. Mode semantics
#### `off`
- no automatic artifact injection,
- no startup/init hint beyond existing tool/docs discovery.
#### `advisory`
- startup/init hints enabled,
- optional root-pair preload,
- light reminders,
- weaker reinjection behavior.
#### `strong`
- root-pair preload required,
- budgeted expansion required,
- relevant-turn reinjection checks required,
- reminders before edits and architecture-sensitive reasoning.
#### `strict`
- everything in `strong`, plus:
- when protocol path is missing during sensitive actions, require explicit bypass justification.
### 7. Relevant-turn detection
`strong` mode should not rescan on every turn.
Relevant-turn triggers should be mapped to concrete runtime signals where possible:
- agent start,
- edit intent / edit tool preparation,
- architecture-sensitive planning prompts,
- compaction completion,
- root-pair artifact change detection.
This will likely require some combination of:
- hook-local heuristics,
- observed tool calls,
- file timestamp/hash checks for root artifacts,
- compaction event handling.
### 8. Visibility model
The design should preserve mixed visibility.
- startup hints: visible and inspectable,
- raw injected artifact blocks: agent-visible by default,
- the fact that automatic injection exists should remain discoverable.
The implementation may use hidden custom message types for artifact payloads, but should not make startup/init behavior opaque.
### 9. Validation strategy
This change is validation-heavy.
Unit tests alone are not enough, because the main risk is runtime interaction between hooks, message mutation, compaction, and reinjection.
#### Integration focus areas
- startup before init,
- startup after init,
- root-pair marker insertion,
- reinjection suppression when marker already exists,
- reinjection after compaction,
- reinjection after artifact mutation,
- mode differences,
- strict-mode bypass path,
- mixed visibility expectations,
- synthetic event-sequence coverage for relevant-turn heuristics such as edit-intent, architecture-sensitive reasoning, compaction, and artifact invalidation.
### 10. Documentation impact
Runtime guidance docs must align with the spec, but retrieval docs remain separate.
Docs should teach:
- startup hint before init,
- root-pair automatic preload after init,
- trust boundary,
- mode ladder,
- relevant-turn reinjection behavior,
- integration-test importance.
## Risks
| Risk | Mitigation |
|---|---|
| Message-level scanning misses provider serialization quirks | Add payload fallback via `before_provider_request` |
| Root-pair marker becomes brittle | Use deterministic boundaries and normalized artifact identity lines |
| 15% + 100k is too aggressive in some fleets | Keep both knobs configurable and document the opinionated default |
| Relevant-turn detection becomes fuzzy | Centralize detection heuristics and prove them with integration tests |
| `strict` mode causes friction | Keep `strong` as default and isolate strict-only bypass behavior |
## Settled defaults
- Root pair is always guaranteed after init.
- Reinjection avoidance is based on canonical outgoing-context scanning.
- Retrieval remains out of scope.
- Mixed visibility is the intended baseline.
- Four modes exist, with `strong` as default.
- Default budget is 15% of active context window, capped at 100k tokens.
openspec/changes/archive/2026-06-11-project-map-prompt-injection/proposal.md
+88
View File
@@ -0,0 +1,88 @@
# Proposal: Project Map Prompt Injection
## Status
| Field | Value |
|---|---|
| Phase | **Proposal** |
| Based on | Grill Me checkpoint + runtime/doc inspection |
| Next | Spec |
## Problem
`pi-project-map` currently provides strong generated artifacts and tool surfaces, but weak automatic runtime guidance.
Today the repo has:
- a one-time `before_agent_start` hint,
- a `session_start` dirty-state UI notification,
- tool metadata and docs,
- generated `.pi-map.md` / `.pi-map.index.md` artifacts.
But it lacks a clear spec for:
1. when maps/indexes should be injected automatically,
2. how much should be injected under a context budget,
3. how reinjection should avoid wasting prompt space,
4. how visible that guidance should be to the user,
5. how strong enforcement should be,
6. how to validate this behavior with integration tests.
## Proposed change
Adopt a runtime prompt-injection policy for project-map that:
- always injects the **root pair** after init,
- expands outward under a **hybrid context budget cap**,
- avoids redundant reinjection by scanning the actual outgoing context,
- keeps **retrieval guidance separate** from this spec,
- exposes **four configurable guidance modes** (`off`, `advisory`, `strong`, `strict`),
- uses **mixed visibility**: user-visible startup hints, agent-visible artifact injection,
- requires **extensive integration tests** for reinjection and context-scanning behavior.
## In scope
- [ ] Define pre-init startup hint behavior
- [ ] Define post-init automatic root-pair preload behavior
- [ ] Define hybrid budget defaults and config shape
- [ ] Define outgoing-context scanning for reinjection avoidance
- [ ] Define visibility model for hints vs injected artifacts
- [ ] Define configurable guidance-strength modes and default
- [ ] Define relevant-turn reinjection triggers for `strong`
- [ ] Define strict-mode bypass-justification behavior at the spec level
- [ ] Define validation and integration-test expectations
- [ ] Define implementation slices for runtime hooks/config/tests/docs
## Out of scope
- [ ] Redesign retrieval ranking or `project_map_context`
- [ ] Merge retrieval behavior into this policy spec
- [ ] Redesign paired artifact contents
- [ ] Introduce vector stores, Engram, or external retrieval backends
- [ ] Guarantee provider-agnostic perfect token counting beyond best-effort budgeting
## Decisions from grilling
| Topic | Decision |
|---|---|
| Change slug | `project-map-prompt-injection` |
| Scope split | Retrieval remains a separate spec |
| Pre-init | Inject only a lightweight `project_map_init` hint |
| Fake/synthetic maps before init | No |
| Guaranteed minimum | Always inject root `.pi-map.index.md` + root `.pi-map.md` |
| Budget model | Hybrid cap |
| Budget config | Relative percentage + optional absolute cap; smaller wins |
| Budget default | 15% of context window, capped at 100k tokens |
| Reinjection avoidance | Canonical marker scanning in actual outgoing context |
| Visibility | Mixed |
| Mode set | `off`, `advisory`, `strong`, `strict` |
| Default mode | `strong` |
| `strong` triggers | Relevant turns only |
| Validation | Extensive integration tests required |
## Success criteria
- [ ] The spec clearly defines what is injected before and after init
- [ ] The spec clearly defines how much is injected and how budgets are applied
- [ ] The spec clearly defines when reinjection checks happen and how duplicates are avoided
- [ ] The spec clearly defines mode semantics and the default mode
- [ ] The spec clearly separates runtime injection policy from retrieval behavior
- [ ] The implementation plan can be executed in narrow, reviewable slices
- [ ] The validation section makes integration coverage a first-class requirement
openspec/changes/archive/2026-06-11-project-map-prompt-injection/spec.md
+226
View File
@@ -0,0 +1,226 @@
# Spec: Project Map Prompt Injection
## Status
| Field | Value |
|---|---|
| Phase | **Spec** |
| Based on | [Proposal](proposal.md) |
| Next | Design |
## Overview
`pi-project-map` must define a deliberate automatic runtime guidance model for map/index usage. After init, the system should preload the root pair, expand under a bounded context budget, avoid redundant reinjection by inspecting actual outgoing context, and scale enforcement through configurable guidance modes.
This spec covers **automatic injection and maintenance guidance only**. Retrieval behavior remains covered by `map-context-retrieval`.
## Decisions
| # | Question | Answer |
|---|---|---|
| 1 | Retrieval included in this spec | No |
| 2 | Pre-init behavior | Lightweight init hint only |
| 3 | Synthetic map content before init | No |
| 4 | Guaranteed post-init minimum | Always inject root pair |
| 5 | Budget model | Hybrid cap |
| 6 | Budget knobs | Relative percentage + optional absolute cap |
| 7 | Budget default | 15% of context window, capped at 100k tokens |
| 8 | Reinjection avoidance | Canonical marker scan in outgoing context/payload |
| 9 | Visibility | Mixed |
| 10 | Mode set | `off`, `advisory`, `strong`, `strict` |
| 11 | Default mode | `strong` |
| 12 | `strong` reinjection cadence | Relevant turns only |
| 13 | Validation expectation | Extensive integration coverage |
## Functional requirements
### 1. Pre-init behavior
Before generated map/index artifacts exist, the extension must inject only a lightweight startup hint.
#### Required behavior
- The hint must tell the agent that the project-map extension is active.
- The hint must instruct the agent to run `project_map_init`.
- The hint must not claim that real map/index artifacts already exist.
- The system must not inject synthetic or fake map content before real artifacts are generated.
### 2. Post-init guaranteed preload
After real artifacts exist, the system must guarantee a minimum preload of the root pair:
- root `.pi-map.index.md`
- root `.pi-map.md`
This root pair is the minimum automatic preload before budgeted expansion begins.
### 3. Trust boundary
The runtime policy must encode the trust boundary:
> **index routes, map orients, source decides**
Required implications:
1. Indexes are navigation aids, not final authority.
2. Maps provide orientation and architectural context, not final authority.
3. Source must remain the final authority before edits or exact behavioral claims.
4. If injected artifacts and source disagree, source wins.
### 4. Budget model
Automatic expansion beyond the root pair must use a hybrid context budget cap.
#### Knobs
The system must support:
- a **relative context-budget percentage**,
- an **optional absolute token cap**.
If both are configured, the smaller effective budget wins.
#### Default budget
The default must be:
- **15%** of the active model context window,
- **100k tokens** absolute cap,
- use the smaller effective budget.
#### Context-window discovery and fallback
- The runtime should derive the active model context window from Pi model metadata when available.
- If the active model context window is unavailable, the runtime must still honor the absolute cap.
- In that fallback case, implementations may skip the relative calculation and use the absolute cap as the effective budget.
#### Expansion rules
- Root pair injection happens before budgeted expansion.
- Additional map/index artifacts are added only while the budget allows.
- The expansion strategy should prefer shallow, high-value structural coverage over deep indiscriminate expansion.
- The spec does not require exact provider-token parity; best-effort budgeting is acceptable if it is deterministic and auditable.
### 5. Reinjection avoidance
The extension must avoid redundant reinjection once the root pair is already in active outgoing context.
#### Required definition
"Already in context" must be defined by scanning the **actual outgoing context**, not only by session guesses.
#### Required behavior
- Before reinjecting, scan per-turn `event.messages` for a stable canonical marker or normalized injected root-pair block.
- If message-layer evidence is insufficient, the runtime may additionally inspect the final provider payload.
- Inject only when the canonical root-pair marker/block is absent.
- The spec must allow implementation via explicit scanning logic even if Pi does not expose a convenience API.
### 6. Visibility model
The system must use mixed visibility.
#### Required behavior
- Lightweight startup/init hints should be user-visible and inspectable.
- Automatic artifact injection may remain agent-visible by default.
- The spec should preserve debuggability: implementations should make the presence of automatic guidance discoverable, even when raw artifact blocks are not fully dumped to the user on every turn.
### 7. Guidance-strength modes
The system must support four named modes:
- `off`
- `advisory`
- `strong`
- `strict`
#### Protocol path definition
For this spec, the **protocol path** is present when the current outgoing context contains:
1. the canonical injected root-pair block, or an equivalent canonical marker proving that root `.pi-map.index.md` and root `.pi-map.md` are already present, and
2. the trust-boundary instruction establishing that `index routes, map orients, source decides`.
If either element is missing for a sensitive action, the protocol path is missing.
#### Mode semantics
- **`off`**
- no automatic injection beyond tool/docs discovery.
- **`advisory`**
- inject startup/init hints,
- allow optional root-pair preload,
- use light reminders.
- **`strong`**
- inject root pair,
- expand under the configured budget,
- run reinjection checks on relevant turns,
- remind before edits or architecture-sensitive reasoning.
- **`strict`**
- same as `strong`, plus:
- require explicit bypass justification before sensitive edits or architectural claims when the protocol path is missing.
#### Default mode
The default mode must be **`strong`**.
### 8. `strong`-mode trigger timing
In `strong` mode, reinjection checks must happen on relevant turns only.
Required triggers:
- agent start,
- before edits,
- before architecture-sensitive reasoning,
- after compaction,
- after root-pair artifact changes.
Required non-trigger:
- do not rescan on every trivial turn.
### 9. Implementation surfaces
The runtime may achieve this behavior through a combination of:
- startup hooks,
- per-turn context hooks,
- provider-payload hooks,
- prompt guidance,
- generated root artifacts.
The spec intentionally does **not** require one exact implementation mechanism, but it does require the observable runtime behavior above.
### 10. Validation requirements
The implementation must be proven with extensive integration coverage.
At minimum, integration coverage must validate:
- pre-init hint behavior,
- post-init root-pair injection,
- budgeted expansion behavior,
- canonical-marker dedupe,
- reinjection after compaction,
- reinjection after root-pair artifact changes,
- mixed visibility behavior,
- guidance-mode differences,
- strict-mode bypass behavior where implemented.
## Non-functional requirements
- Keep the policy explicit and auditable.
- Keep retrieval out of scope for this spec.
- Prefer deterministic behavior over opaque heuristics where possible.
- Optimize for modern large-context models, while retaining a hard ceiling.
- Preserve source as final authority.
## User flows
### Flow 1: New repo, maps not initialized
1. Agent starts in a repo without project-map artifacts.
2. Runtime injects a lightweight visible startup hint.
3. Agent is instructed to run `project_map_init`.
4. No fake artifact content is injected.
### Flow 2: Normal initialized repo in `strong` mode
1. Agent starts.
2. Runtime checks outgoing context for canonical root-pair marker.
3. If absent, inject root pair and budgeted expansion.
4. On relevant later turns, runtime rescans only when trigger conditions apply.
5. Before edits, agent is reminded to use injected context and then verify source.
### Flow 3: Compaction or artifact invalidation
1. Context compacts or root-pair artifacts change.
2. Runtime treats that as a relevant reinjection trigger.
3. Runtime rescans outgoing context.
4. If canonical root-pair block is absent, inject again.
### Flow 4: Strict-mode sensitive action
1. Agent approaches a sensitive edit or architectural claim.
2. Runtime checks whether the protocol path is present.
3. If not, runtime requires explicit bypass justification before proceeding.
## Acceptance criteria
- [ ] Pre-init behavior is hint-only and never injects fake map content
- [ ] Post-init behavior always guarantees root pair preload before budgeted expansion
- [ ] Budgeting supports both relative and absolute caps, with the smaller effective budget winning
- [ ] Default budget is 15% of active context window, capped at 100k tokens, with absolute-cap fallback when context-window metadata is unavailable
- [ ] Reinjection avoidance is based on actual outgoing-context scanning
- [ ] Mixed visibility is honored
- [ ] Four guidance modes exist with `strong` as default
- [ ] `strong` checks fire on relevant turns only
- [ ] `strict` adds bypass-justification semantics for missing protocol path on sensitive actions
- [ ] Extensive integration tests cover context scanning and reinjection behavior
openspec/changes/archive/2026-06-11-project-map-prompt-injection/sync-report.md
+7
View File
@@ -0,0 +1,7 @@
# Sync Report
Status: NOT-APPLICABLE
Reason: This repository uses legacy flat change artifacts (proposal.md/spec.md/design.md/tasks.md) and does not maintain a canonical openspec/specs/ tree for these changes. No canonical spec sync was performed.
User-approved fallback: archive completed change as an audit record without canonical spec sync.
openspec/changes/archive/2026-06-11-project-map-prompt-injection/tasks.md
+90
View File
@@ -0,0 +1,90 @@
# Tasks: Project Map Prompt Injection
## Status
| Field | Value |
|---|---|
| Phase | **Tasks** |
| Based on | [Design](design.md) |
| Next | Apply |
## Delivery slices
### Slice 1: Injection policy scaffold and config surface
**Scope**: mode/config scaffolding, pre-init hint behavior, canonical helper boundaries
**Review goal**: establish the policy control surface without yet wiring the full runtime pipeline
**Tasks**:
1. [ ] Add a shared prompt-injection policy helper/module
2. [ ] Add config support for injection mode, context-budget percent, and absolute cap using additive flat JSON keys compatible with existing `.pi-project-map.json` loading
3. [ ] Decide and document how existing `contextBudget` interacts with the new injection-budget knobs
4. [ ] Implement pre-init startup-hint behavior with no synthetic artifact injection
5. [ ] Define canonical marker/block construction for injected root-pair content
6. [ ] Add/update tests for config loading and pre-init hint behavior
### Slice 2: Root-pair preload and budgeted expansion
**Scope**: post-init preload, budget calculation, artifact selection under cap
**Review goal**: make automatic injection materially real after init
**Tasks**:
1. [ ] Implement guaranteed root-pair preload after init
2. [ ] Implement effective-budget calculation using percent + absolute cap with smaller-wins semantics
3. [ ] Implement active-model context-window discovery and explicit absolute-cap fallback when metadata is unavailable
4. [ ] Implement deterministic budgeted expansion beyond the root pair
5. [ ] Keep retrieval explicitly out of this injection path
6. [ ] Add/update tests for root-pair guarantee, context-window fallback, and budget-capped expansion
### Slice 3: Reinjection avoidance and relevant-turn checks
**Scope**: outgoing-context scanning, relevant-turn triggers, compaction/artifact invalidation
**Review goal**: avoid wasteful reinjection while preserving strong guidance
**Tasks**:
1. [ ] Implement canonical marker scanning over `event.messages`
2. [ ] Add fallback inspection of final provider payload when needed
3. [ ] Implement relevant-turn reinjection triggers for `strong` mode
4. [ ] Reinject after compaction and after root-pair artifact changes
5. [ ] Add/update integration tests for dedupe, reinjection suppression, and reinjection after invalidation
6. [ ] Include synthetic event-sequence coverage for edit-intent, architecture-sensitive reasoning, compaction, and artifact-change heuristics
### Slice 4: Mode semantics, visibility, and strict-path behavior
**Scope**: off/advisory/strong/strict semantics, mixed visibility, strict bypass behavior
**Review goal**: make the mode ladder operational and reviewable
**Tasks**:
1. [ ] Implement mode-specific behavior for `off`, `advisory`, `strong`, and `strict`
2. [ ] Define and enforce the spec meaning of a missing `protocol path` during sensitive actions
3. [ ] Keep startup hints user-visible and artifact injection agent-visible by default
4. [ ] Implement strict-mode explicit bypass-justification behavior for sensitive edits/architectural claims
5. [ ] Add/update integration tests for visibility, protocol-path detection, and mode differences
6. [ ] Verify that `strong` remains the default behavior
### Slice 5: Documentation and runtime alignment
**Scope**: docs, runtime guidance text, implementation notes
**Review goal**: align user-facing/runtime-facing guidance with the frozen spec
**Tasks**:
1. [ ] Update runtime guidance strings to reflect init-hint behavior, root-pair preload, trust boundary, and mode ladder
2. [ ] Update docs/skill guidance for the prompt-injection policy
3. [ ] Keep retrieval guidance separate from these docs or clearly reference it as separate
4. [ ] Document the opinionated default budget and configurability
5. [ ] Summarize integration-test expectations and known risks
## Acceptance checklist
- [x] Before init, only a lightweight `project_map_init` hint is injected
- [x] No synthetic map/index artifact content is injected before init
- [x] After init, root `.pi-map.index.md` and root `.pi-map.md` are always guaranteed before budgeted expansion
- [x] Expansion uses a hybrid cap with both relative and absolute knobs, smaller effective budget wins
- [x] Default budget is 15% of active context window, capped at 100k tokens
- [x] Reinjection avoidance is based on canonical marker scanning in actual outgoing context
- [x] `strong` checks only relevant turns, not every trivial turn
- [x] Modes `off`, `advisory`, `strong`, and `strict` are implemented with the agreed semantics
- [x] Mixed visibility behavior is preserved
- [x] Retrieval behavior remains separate from this spec’s implementation scope
- [x] Extensive integration tests validate context scanning and reinjection behavior
- [x] `npm run typecheck` passes
- [x] `npm test` passes
- [x] `npm run lint` passes *(N/A: repo has no ESLint config; pre-existing repository gap, not a change regression)*
## Review workload note
This change mixes runtime hook behavior, prompt budgeting, context dedupe, visibility policy, and strict-mode enforcement. Keep delivery narrow and test-heavy. Avoid collapsing this into one oversized implementation slice.
openspec/changes/archive/2026-06-11-project-map-prompt-injection/verify-report.md
+22
View File
@@ -0,0 +1,22 @@
# Verify Report
Status: PASS
Change: project-map-prompt-injection
Verified summary: Implemented prompt-injection slices 1-5: mode/config surface, root-pair preload, reinjection/dedupe, strict/advisory/strong/off semantics, and documentation/runtime alignment.
Evidence commands:
- npm run typecheck
- npx vitest run
- npm run build
- node dist/cli.js validate .
Current validation state:
- npm run typecheck: PASS
- npx vitest run: PASS (262/262)
- npm run build: PASS
- node dist/cli.js validate .: PASS
Notes:
- Repo-wide lint remains unavailable because the repository has no ESLint config; treated as a pre-existing repository-level gap, not a change regression.