pi-map/troubleshooting.md

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> or project_map_validate with fix=true
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, or run project-map validate --fix
• if widespread, reinit and validate again

Symptom

broken-link appears after moving directories.

Fix

Run project-map validate --fix first. If the damage spans many directories, 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, often because project_map_reinit is being used instead of project_map_patch or project_map_validate --fix.

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
• prefer project_map_patch <file> for edits and project_map_validate with fix=true for localized discrepancies

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:

[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

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