89 lines
3.7 KiB
Markdown
89 lines
3.7 KiB
Markdown
# 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
|