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

# 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