pi-map/openspec/changes/archive/2026-06-11-project-map-prompt-injection/spec.md

Spec: Project Map Prompt Injection

Status

Field	Value
Phase	Spec
Based on	Proposal
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