CODEX.md

Dual-Graph Context Policy

This project uses a local dual-graph MCP server for efficient context retrieval.

Context Layering (Codex Only)

• Use layered context files:
  • .dual-graph-context/PROJECT_CONTEXT.md for stable project context.
  • .dual-graph-context/SESSION_CONTEXT.md for current in-chat scope.
  • .dual-graph-context/packs/*.md for domain-specific context packs.
• Never ask for "full context" or entire chat history.
• Ask only for missing sections, one short question at a time.
• If a domain is missing context, request only that pack (for example: "please share billing context pack").

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 has fewer than 5 files. Do NOT do broad or recursive exploration. Read only specific files if their names are mentioned, or ask the user what to work on.

4. Load context layers before implementation decisions:

   • Read .dual-graph-context/PROJECT_CONTEXT.md and .dual-graph-context/SESSION_CONTEXT.md when available.
   • Read only relevant .dual-graph-context/packs/*.md files for the current task.
   • If critical context is missing, ask one scoped question and continue after answer.

5. Read recommended_files using graph_read — one call per file.

   • graph_read accepts a single file parameter (string). Call it separately for each recommended file. Do NOT pass an array or batch multiple files into one call.
   • 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.
   • Example: if recommended_files is ["src/auth.ts::handleLogin", "src/db.ts"], call graph_read(file: "src/auth.ts::handleLogin") and graph_read(file: "src/db.ts") as two separate calls (they can be parallel).

6. 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.

Rules

• Do NOT use rg, grep, or bash file exploration before calling graph_continue.
• Do NOT do broad/recursive exploration at any confidence level.
• max_supplementary_greps and max_supplementary_files are hard caps - never exceed them.
• Do NOT dump full chat history.
• Do context handshake per task: summarize known context, then ask for only missing pieces.
• Do NOT call graph_retrieve more than once per turn.
• 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.