spec(prompt): add project map prompt injection change set
This commit is contained in:
@@ -0,0 +1,226 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user