82 added, 0 removed. Audit A to A.
# Domain Experts — session bootstrap
Before doing ANY work in this repo, read these three files in full, in this order:
1. `AGENTS.md` — what lives where, the rules, release checklist, known pitfalls
2. `CONTRIBUTING.md` — especially the "Exact recipe for adding a role (follow verbatim)" section
3. `docs/CONTEXT.md` — where the last session left off
## Non-negotiables when adding or editing roles
- New roles are `spec: 2` per `AUTHORING.md`: SKILL.md + `references/` trio, worked example with real reconciling numbers, each idea stated exactly once.
- Order of operations: write files → `git add roles/<slug>` → `python3 scripts/lint_roles.py <slug>` until 0 errors → `python3 scripts/generate_roadmap.py` → commit everything together → `git pull --rebase --autostash` → push.
- Never hand-edit generated content: README role-count block, ROADMAP checklist, `data/roles.json`.
- Another session may be pushing to `main` concurrently — always pull --rebase --autostash before push.
- Quality bar: a practitioner should nod, not shrug. If a role would ship generic, skip it and pick another — an empty slot is recoverable, a generic role poisons trust.
+ <!-- dgc-policy-v11 -->
+ # Dual-Graph Context Policy
+
+ This project uses a local dual-graph MCP server for efficient context retrieval.
+
+ ## 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. **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).
+
+ 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.
+
+ ## Token Usage
+
+ A `token-counter` MCP is available for tracking live token usage.
+
+ - To check how many tokens a large file or text will cost **before** reading it:
+ `count_tokens({text: "<content>"})`
+ - To log actual usage after a task completes (if the user asks):
+ `log_usage({input_tokens: <est>, output_tokens: <est>, description: "<task>"})`
+ - To show the user their running session cost:
+ `get_session_stats()`
+
+ Live dashboard URL is printed at startup next to "Token usage".
+
+ ## 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 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.
+
+ ## Context Store
+
+ Whenever you make a decision, identify a task, note a next step, fact, or blocker during a conversation, call `graph_add_memory`.
+
+ **To add an entry:**
+ ```
+ graph_add_memory(type="decision|task|next|fact|blocker", content="one sentence max 15 words", tags=["topic"], files=["relevant/file.ts"])
+ ```
+
+ **Do NOT write context-store.json directly** — always use `graph_add_memory`. It applies pruning and keeps the store healthy.
+
+ **Rules:**
+ - Only log things worth remembering across sessions (not every minor detail)
+ - `content` must be under 15 words
+ - `files` lists the files this decision/task relates to (can be empty)
+ - Log immediately when the item arises — not at session end
+
+ ## Session End
+
+ When the user signals they are done (e.g. "bye", "done", "wrap up", "end session"), proactively update `CONTEXT.md` in the project root with:
+ - **Current Task**: one sentence on what was being worked on
+ - **Key Decisions**: bullet list, max 3 items
+ - **Next Steps**: bullet list, max 3 items
+
+ Keep `CONTEXT.md` under 20 lines total. Do NOT summarize the full conversation — only what's needed to resume next session.
+