pi-map/openspec/changes/project-map-prompt-injection/proposal.md

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