docs: rewrite documentation system
This commit is contained in:
@@ -0,0 +1,185 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user