|
| 1 | +<!-- dgc-policy-v11 --> |
| 2 | +# Dual-Graph Context Policy |
| 3 | + |
| 4 | +This project uses a local dual-graph MCP server for efficient context retrieval. |
| 5 | + |
| 6 | +## MANDATORY: Always follow this order |
| 7 | + |
| 8 | +1. **Call `graph_continue` first** — before any file exploration, grep, or code reading. |
| 9 | + |
| 10 | +2. **If `graph_continue` returns `needs_project=true`**: call `graph_scan` with the |
| 11 | + current project directory (`pwd`). Do NOT ask the user. |
| 12 | + |
| 13 | +3. **If `graph_continue` returns `skip=true`**: project has fewer than 5 files. |
| 14 | + Do NOT do broad or recursive exploration. Read only specific files if their names |
| 15 | + are mentioned, or ask the user what to work on. |
| 16 | + |
| 17 | +4. **Read `recommended_files`** using `graph_read` — **one call per file**. |
| 18 | + - `graph_read` accepts a single `file` parameter (string). Call it separately for each |
| 19 | + recommended file. Do NOT pass an array or batch multiple files into one call. |
| 20 | + - `recommended_files` may contain `file::symbol` entries (e.g. `src/auth.ts::handleLogin`). |
| 21 | + Pass them verbatim to `graph_read(file: "src/auth.ts::handleLogin")` — it reads only |
| 22 | + that symbol's lines, not the full file. |
| 23 | + - Example: if `recommended_files` is `["src/auth.ts::handleLogin", "src/db.ts"]`, |
| 24 | + call `graph_read(file: "src/auth.ts::handleLogin")` and `graph_read(file: "src/db.ts")` |
| 25 | + as two separate calls (they can be parallel). |
| 26 | + |
| 27 | +5. **Check `confidence` and obey the caps strictly:** |
| 28 | + - `confidence=high` -> Stop. Do NOT grep or explore further. |
| 29 | + - `confidence=medium` -> If recommended files are insufficient, call `fallback_rg` |
| 30 | + at most `max_supplementary_greps` time(s) with specific terms, then `graph_read` |
| 31 | + at most `max_supplementary_files` additional file(s). Then stop. |
| 32 | + - `confidence=low` -> Call `fallback_rg` at most `max_supplementary_greps` time(s), |
| 33 | + then `graph_read` at most `max_supplementary_files` file(s). Then stop. |
| 34 | + |
| 35 | +## Token Usage |
| 36 | + |
| 37 | +A `token-counter` MCP is available for tracking live token usage. |
| 38 | + |
| 39 | +- To check how many tokens a large file or text will cost **before** reading it: |
| 40 | + `count_tokens({text: "<content>"})` |
| 41 | +- To log actual usage after a task completes (if the user asks): |
| 42 | + `log_usage({input_tokens: <est>, output_tokens: <est>, description: "<task>"})` |
| 43 | +- To show the user their running session cost: |
| 44 | + `get_session_stats()` |
| 45 | + |
| 46 | +Live dashboard URL is printed at startup next to "Token usage". |
| 47 | + |
| 48 | +## Rules |
| 49 | + |
| 50 | +- Do NOT use `rg`, `grep`, or bash file exploration before calling `graph_continue`. |
| 51 | +- Do NOT do broad/recursive exploration at any confidence level. |
| 52 | +- `max_supplementary_greps` and `max_supplementary_files` are hard caps - never exceed them. |
| 53 | +- Do NOT dump full chat history. |
| 54 | +- Do NOT call `graph_retrieve` more than once per turn. |
| 55 | +- After edits, call `graph_register_edit` with the changed files. Use `file::symbol` notation (e.g. `src/auth.ts::handleLogin`) when the edit targets a specific function, class, or hook. |
| 56 | + |
| 57 | +## Context Store |
| 58 | + |
| 59 | +Whenever you make a decision, identify a task, note a next step, fact, or blocker during a conversation, call `graph_add_memory`. |
| 60 | + |
| 61 | +**To add an entry:** |
| 62 | +``` |
| 63 | +graph_add_memory(type="decision|task|next|fact|blocker", content="one sentence max 15 words", tags=["topic"], files=["relevant/file.ts"]) |
| 64 | +``` |
| 65 | + |
| 66 | +**Do NOT write context-store.json directly** — always use `graph_add_memory`. It applies pruning and keeps the store healthy. |
| 67 | + |
| 68 | +**Rules:** |
| 69 | +- Only log things worth remembering across sessions (not every minor detail) |
| 70 | +- `content` must be under 15 words |
| 71 | +- `files` lists the files this decision/task relates to (can be empty) |
| 72 | +- Log immediately when the item arises — not at session end |
| 73 | + |
| 74 | +## Session End |
| 75 | + |
| 76 | +When the user signals they are done (e.g. "bye", "done", "wrap up", "end session"), proactively update `CONTEXT.md` in the project root with: |
| 77 | +- **Current Task**: one sentence on what was being worked on |
| 78 | +- **Key Decisions**: bullet list, max 3 items |
| 79 | +- **Next Steps**: bullet list, max 3 items |
| 80 | + |
| 81 | +Keep `CONTEXT.md` under 20 lines total. Do NOT summarize the full conversation — only what's needed to resume next session. |
0 commit comments