CLAUDE.md

Dual-Graph Context Policy

This project uses a local dual-graph MCP server (graperoot-pro) for efficient, budget-aware context retrieval. Always prefer it over native file exploration.

MANDATORY: Always follow this order

1. Call graph_continue first -- before any file exploration, grep, or code reading.

2. If graph_continue returns needs_project=true: call graph_scan with the current project directory (pwd). Do NOT ask the user.

3. If graph_continue returns skip=true: project is too small for the graph to help. Skip all graph tools and explore normally.

4. Read recommended_files using graph_read -- one call per file.

   • recommended_files may contain file::symbol entries (e.g. src/auth.ts::handleLogin). Pass them verbatim to graph_read(file: "src/auth.ts::handleLogin") -- it reads only that symbol's lines, not the full file.

5. Check confidence and obey the caps strictly:

   • confidence=high -> Stop. Do NOT grep or explore further.
   • confidence=medium -> If recommended files are insufficient, call fallback_rg at most max_supplementary_greps time(s) with specific terms, then graph_read at most max_supplementary_files additional file(s). Then stop.
   • confidence=low -> Call fallback_rg at most max_supplementary_greps time(s), then graph_read at most max_supplementary_files file(s). Then stop.

Exhaustive enumeration tasks

Some tasks require scanning every file -- e.g. "find all dead exports", "list every .find() without a limit", "audit all test files". Use these tools first:

• graph_dead_exports() -- pre-computed at scan time. Use for any dead-export task.
• graph_grep_all(pattern, file_glob?, max_hits?) -- exhaustive grep, no call cap.

Rules

• Do NOT use rg, grep, or bash file exploration before calling graph_continue.
• Do NOT do broad/recursive exploration at any confidence level.
• After edits, call graph_register_edit(files: ["path/to/file"]). The parameter is files (plural, always an array). Use file::symbol notation when the edit targets a specific function, class, or hook.