# 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