# Troubleshooting pi-project-map

## Stale map issues

### Symptom
`project_map_validate` reports `missing`, `orphaned`, or `stale-signature` discrepancies, or a directory map describes files that no longer exist.

### Likely cause
A source file was edited, added, or deleted without running `project_map_patch` or `project_map_reinit`.

### What to do
1. run `project_map_validate` to inspect discrepancies
2. if the list is small and localized, run `project_map_patch <changed-file>`
3. if the list is large or structural, run `project_map_reinit`
4. re-run `project_map_validate` to confirm clean state

### Prevention
- patch immediately after editing source
- in Pi, use the `project_map_patch` tool with the changed file path
- watch for the `session_start` dirty warning

## Validate discrepancies

### Symptom
`validate --fix` fails with `validate --fix requires an LLM client`.

### Cause
Repair needs an LLM client to regenerate stale artifacts.

### Fix
- CLI: provide `--llm-provider=...` and the required API key
- Pi: use the tool surface so the runtime provides the LLM client

### Symptom
Many `stale-signature` discrepancies appear.

### Cause
AST exports no longer match listed exports, or generated signatures are stale.

### Fix
- patch the changed file/directory
- if widespread, reinit and validate again

### Symptom
`broken-link` appears after moving directories.

### Fix
Run `project_map_reinit`.

## Prompt injection mode surprises

### Symptom
No project-map context appears in a Pi session.

### Checks before init
1. confirm `.pi-project-map.json` does not set `promptInjectionMode` to `off`
2. confirm root `.pi-map.md` / `.pi-map.index.md` do not exist yet
3. confirm the session is at agent start; the pre-init hint is emitted from `before_agent_start`

### Checks after init
1. confirm root `.pi-map.md` and `.pi-map.index.md` exist
2. confirm mode is `strong` or `strict` if you expect automatic artifact injection
3. confirm the outgoing context does not already contain the root-pair marker
4. confirm the turn is actually relevant (`agent_start`, `edit_intent`, `architecture_sensitive`, `compaction`, `artifact_change`)

### Symptom
Root pair is injected repeatedly.

### Likely cause
Marker scanning failed or artifact invalidation forced reinjection.

### Fix
- inspect whether `<!-- PI_MAP_ROOT_PAIR_START -->` is present in outgoing context
- check whether root artifacts changed on disk
- confirm payload/message serialization still exposes marker text

### Symptom
`advisory` mode shows a reminder but no maps are loaded.

### Expected behavior
That is intentional. Advisory mode is reminder-only; read the root pair manually.

## Strict bypass confusion

### Symptom
A sensitive edit is blocked with the strict guard.

### What is happening
In `strict` mode, the turn was classified as sensitive and the protocol path is missing from outgoing context.

### Resolution options
1. restore the protocol path by ensuring the root pair and trust boundary are present in context
2. include an explicit bypass marker:

```text
[PI_MAP_BYPASS: emergency fix needed without full context]
```

3. switch to `strong` mode if strict is too noisy for the task

### Symptom
Bypass marker is ignored.

### Cause
The marker must contain a non-empty reason. Empty or whitespace-only reasons are rejected.

### Symptom
Strict guard triggers on obviously non-sensitive turns.

### Cause
Heuristic sensitive-turn detection can false-positive on words like `refactor`, `redesign`, or `dependency graph`.

## LLM / provider / cache issues

### Symptom
`project-map init` fails with `No LLM client configured`.

### CLI fix
- set `OPENAI_API_KEY` for OpenAI provider
- set `KIMI_API_KEY` for Kimi provider
- or configure provider/model in `.pi-project-map.json`

### Pi fix
- select a model in Pi
- log in if the provider requires credentials
- ensure Pi runtime LLM access is working

### Symptom
External/provider request fails.

### Checks
1. API key validity
2. network connectivity
3. `llmBaseUrl` correctness if using a proxy
4. provider rate limits

### Symptom
Second init still makes many LLM calls.

### Cause
Cache miss.

### Checks
- consistent cache directory between runs
- cache file exists and is readable
- file contents did not change

### Symptom
Cache file is huge.

### Cause
There is no eviction policy yet.

### Fix
Remove the local cache directory if needed.

## Test / lint expectations

### Main checks

```bash
npm test
npm run typecheck
npm run build
node dist/cli.js validate .
```

### Lint note
`npm run lint` is currently not a reliable gate if the repo has no ESLint config. Treat missing-lint-config failures as repository hygiene issues, not feature regressions.

### Common failures

| Failure | Likely cause |
|---------|--------------|
| Pi LLM client tests fail | Pi runtime or mocks drifted |
| Prompt-injection sequence tests fail | Reinjection / strict logic changed |
| Validate tests fail | Format parsing, merge encoding, or discovery rules changed |
| AST tests fail | tree-sitter grammar/runtime drift |

## Known limitations

- token budgeting is heuristic, not tokenizer-exact
- retrieval is deterministic, not semantic-search-driven
- strict mode is a prompt-level guard, not a hard tool sandbox
- payload scanning assumes string or JSON-serializable structures