186 lines
5.2 KiB
Markdown
186 lines
5.2 KiB
Markdown
# 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
|