docs(routing): align Codex and Claude agent guidance

docs/MODEL_ROUTING_AGENTS.md

@@ -0,0 +1,35 @@
+# Model Routing in Codex and Claude Code
+
+Codex and Claude Code use the same `mq-mcp` server, routing tools, and
+versioned contracts in VS Code. The local Ollama candidate is advisory; the
+active coding agent remains authoritative.
+
+## Codex example
+
+For `Review the mq-hal route status implementation`:
+
+1. Codex calls `mq_route_inspect` with the task.
+2. For cross-repo evidence, Codex calls `mq_context_pack`.
+3. Codex may call `mq_route_shadow`, but never treats its candidate as accepted.
+4. Codex verifies findings against source and tests.
+5. Codex escalates when the decision contains an escalation condition.
+
+## Claude Code example
+
+Claude Code follows the same sequence because `CLAUDE.md` imports `@AGENTS.md`:
+
+1. Call `mq_route_inspect` before planning the non-trivial change.
+2. Call `mq_context_pack` when the task crosses repository boundaries.
+3. Use `mq_route_shadow` only as additional evidence.
+4. Keep Claude authoritative for medium/high-risk work.
+5. Verify against source and tests; escalate on the same reason codes.
+
+## Boundaries
+
+- Do not replace either agent's model backend.
+- Do not intercept every editor prompt.
+- Do not execute or persist a shadow candidate automatically.
+- Do not implement separate routing policy for Codex and Claude.
+
+The tools are documented by `mq-mcp`; routing policy and decision/outcome
+contracts are owned by `mq-agent`.

examples/generated-agent-entrypoints/macos-scripts/AGENTS.md

@@ -44,31 +44,27 @@ Stop reading as soon as the task is grounded.
 
 - Prefer task packs and agent views over full notes.
 - Prefer hot/index over pattern notes.
-- Do not scan the whole vault by default.
-- Do not open multiple pattern notes unless clearly needed.
-- Summarize instead of replaying long note bodies.
+- Do not scan the whole vault or several pattern notes by default.
+- Summarize instead of replaying note bodies.
 
 ## Rules
 
 - Do not duplicate logic owned by another MQ repo.
 - Prefer JSON contracts over free-text coupling.
-- Keep repo boundaries explicit.
-- Use `mqobsidian` only as durable memory, not runtime truth.
-- Verify current code behavior, tests, contracts, and CLI behavior in this repo.
+- Keep repo boundaries explicit; use `mqobsidian` as memory, not runtime truth.
+- Verify current code, tests, contracts, and CLI behavior in this repo.
 
 ## Durable Memory
 
-MQ-stack memory lives in `mqobsidian`. Use generated context packs before
-reading large docs.
+MQ-stack memory lives in `mqobsidian`; use context packs before large docs.
 
 `mqobsidian` is durable memory, not live runtime truth. If the task depends on
 current code behavior, tests, contracts, CLI behavior, or runtime state, verify
 in this repo before making claims.
 
 ## Observation Emission
 
-After evidence-backed work reveals a reusable pattern, workflow, convention, or
-review finding, emit one observation:
+After evidence-backed work reveals a reusable pattern or finding, emit one observation:
 
 ```bash
 uv --directory ${MQ_OBSIDIAN_DIR:-$HOME/mqobsidian}/memory run python commands/emit_observation.py \
@@ -83,19 +79,24 @@ Do not emit secrets, private paths, raw logs, chain-of-thought, or unevidenced o
 
 ## Source Intelligence
 
-If `.codegraph/` exists, prefer CodeGraph for source-structure questions before
-broad file scans: symbol lookup, callers/callees, impact analysis, code-flow.
+If `.codegraph/` exists, use CodeGraph MCP before broad scans:
+`codegraph_context` first; use trace/explore/impact as the task requires.
+Treat returned source as read; use targeted reads only for missing, stale, or
+unsupported detail. Use `mqobsidian` for durable memory and repo boundaries.
 
-Do not use CodeGraph as durable MQ memory. Use `mqobsidian` context packs and
-cards for memory, repo boundaries, and prior verified work.
+## MQ Model Routing
+
+Before a non-trivial change, call `mq_route_inspect`; for cross-repo work also
+call `mq_context_pack`. Treat `mq_route_shadow` only as advisory evidence.
+Codex or Claude stays authoritative for medium/high-risk work. Verify against
+repo code/tests and escalate when the router reports an escalation condition.
 
 ## Writing Rules
 
 When creating notes, summaries, or exports:
 
 - separate facts, interpretation, and recommendation
-- keep outputs compact
-- preserve timestamps and provenance when relevant
+- keep outputs compact; preserve timestamps and provenance when relevant
 - prefer links over duplicated prose
 - avoid raw dumps
 
@@ -104,9 +105,8 @@ or machine-specific private paths.
 
 ## MQ Skills
 
-Use repo-local skills from `.agents/skills/` (Codex) and `.claude/skills/`
-(Claude Code); route by frontmatter `description`. Near-universal:
-`mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`.
+Use `.agents/skills/` (Codex) and `.claude/skills/` (Claude); route by frontmatter
+`description`. Common: `mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`.
 
 ## Codex Governor
 

examples/generated-agent-entrypoints/mcamner-journal/AGENTS.md

@@ -44,31 +44,27 @@ Stop reading as soon as the task is grounded.
 
 - Prefer task packs and agent views over full notes.
 - Prefer hot/index over pattern notes.
-- Do not scan the whole vault by default.
-- Do not open multiple pattern notes unless clearly needed.
-- Summarize instead of replaying long note bodies.
+- Do not scan the whole vault or several pattern notes by default.
+- Summarize instead of replaying note bodies.
 
 ## Rules
 
 - Do not duplicate logic owned by another MQ repo.
 - Prefer JSON contracts over free-text coupling.
-- Keep repo boundaries explicit.
-- Use `mqobsidian` only as durable memory, not runtime truth.
-- Verify current code behavior, tests, contracts, and CLI behavior in this repo.
+- Keep repo boundaries explicit; use `mqobsidian` as memory, not runtime truth.
+- Verify current code, tests, contracts, and CLI behavior in this repo.
 
 ## Durable Memory
 
-MQ-stack memory lives in `mqobsidian`. Use generated context packs before
-reading large docs.
+MQ-stack memory lives in `mqobsidian`; use context packs before large docs.
 
 `mqobsidian` is durable memory, not live runtime truth. If the task depends on
 current code behavior, tests, contracts, CLI behavior, or runtime state, verify
 in this repo before making claims.
 
 ## Observation Emission
 
-After evidence-backed work reveals a reusable pattern, workflow, convention, or
-review finding, emit one observation:
+After evidence-backed work reveals a reusable pattern or finding, emit one observation:
 
 ```bash
 uv --directory ${MQ_OBSIDIAN_DIR:-$HOME/mqobsidian}/memory run python commands/emit_observation.py \
@@ -83,19 +79,24 @@ Do not emit secrets, private paths, raw logs, chain-of-thought, or unevidenced o
 
 ## Source Intelligence
 
-If `.codegraph/` exists, prefer CodeGraph for source-structure questions before
-broad file scans: symbol lookup, callers/callees, impact analysis, code-flow.
+If `.codegraph/` exists, use CodeGraph MCP before broad scans:
+`codegraph_context` first; use trace/explore/impact as the task requires.
+Treat returned source as read; use targeted reads only for missing, stale, or
+unsupported detail. Use `mqobsidian` for durable memory and repo boundaries.
 
-Do not use CodeGraph as durable MQ memory. Use `mqobsidian` context packs and
-cards for memory, repo boundaries, and prior verified work.
+## MQ Model Routing
+
+Before a non-trivial change, call `mq_route_inspect`; for cross-repo work also
+call `mq_context_pack`. Treat `mq_route_shadow` only as advisory evidence.
+Codex or Claude stays authoritative for medium/high-risk work. Verify against
+repo code/tests and escalate when the router reports an escalation condition.
 
 ## Writing Rules
 
 When creating notes, summaries, or exports:
 
 - separate facts, interpretation, and recommendation
-- keep outputs compact
-- preserve timestamps and provenance when relevant
+- keep outputs compact; preserve timestamps and provenance when relevant
 - prefer links over duplicated prose
 - avoid raw dumps
 
@@ -104,9 +105,8 @@ or machine-specific private paths.
 
 ## MQ Skills
 
-Use repo-local skills from `.agents/skills/` (Codex) and `.claude/skills/`
-(Claude Code); route by frontmatter `description`. Near-universal:
-`mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`.
+Use `.agents/skills/` (Codex) and `.claude/skills/` (Claude); route by frontmatter
+`description`. Common: `mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`.
 
 ## Codex Governor
 

examples/generated-agent-entrypoints/mq-agent/AGENTS.md

@@ -44,31 +44,27 @@ Stop reading as soon as the task is grounded.
 
 - Prefer task packs and agent views over full notes.
 - Prefer hot/index over pattern notes.
-- Do not scan the whole vault by default.
-- Do not open multiple pattern notes unless clearly needed.
-- Summarize instead of replaying long note bodies.
+- Do not scan the whole vault or several pattern notes by default.
+- Summarize instead of replaying note bodies.
 
 ## Rules
 
 - Do not duplicate logic owned by another MQ repo.
 - Prefer JSON contracts over free-text coupling.
-- Keep repo boundaries explicit.
-- Use `mqobsidian` only as durable memory, not runtime truth.
-- Verify current code behavior, tests, contracts, and CLI behavior in this repo.
+- Keep repo boundaries explicit; use `mqobsidian` as memory, not runtime truth.
+- Verify current code, tests, contracts, and CLI behavior in this repo.
 
 ## Durable Memory
 
-MQ-stack memory lives in `mqobsidian`. Use generated context packs before
-reading large docs.
+MQ-stack memory lives in `mqobsidian`; use context packs before large docs.
 
 `mqobsidian` is durable memory, not live runtime truth. If the task depends on
 current code behavior, tests, contracts, CLI behavior, or runtime state, verify
 in this repo before making claims.
 
 ## Observation Emission
 
-After evidence-backed work reveals a reusable pattern, workflow, convention, or
-review finding, emit one observation:
+After evidence-backed work reveals a reusable pattern or finding, emit one observation:
 
 ```bash
 uv --directory ${MQ_OBSIDIAN_DIR:-$HOME/mqobsidian}/memory run python commands/emit_observation.py \
@@ -83,19 +79,24 @@ Do not emit secrets, private paths, raw logs, chain-of-thought, or unevidenced o
 
 ## Source Intelligence
 
-If `.codegraph/` exists, prefer CodeGraph for source-structure questions before
-broad file scans: symbol lookup, callers/callees, impact analysis, code-flow.
+If `.codegraph/` exists, use CodeGraph MCP before broad scans:
+`codegraph_context` first; use trace/explore/impact as the task requires.
+Treat returned source as read; use targeted reads only for missing, stale, or
+unsupported detail. Use `mqobsidian` for durable memory and repo boundaries.
 
-Do not use CodeGraph as durable MQ memory. Use `mqobsidian` context packs and
-cards for memory, repo boundaries, and prior verified work.
+## MQ Model Routing
+
+Before a non-trivial change, call `mq_route_inspect`; for cross-repo work also
+call `mq_context_pack`. Treat `mq_route_shadow` only as advisory evidence.
+Codex or Claude stays authoritative for medium/high-risk work. Verify against
+repo code/tests and escalate when the router reports an escalation condition.
 
 ## Writing Rules
 
 When creating notes, summaries, or exports:
 
 - separate facts, interpretation, and recommendation
-- keep outputs compact
-- preserve timestamps and provenance when relevant
+- keep outputs compact; preserve timestamps and provenance when relevant
 - prefer links over duplicated prose
 - avoid raw dumps
 
@@ -104,9 +105,8 @@ or machine-specific private paths.
 
 ## MQ Skills
 
-Use repo-local skills from `.agents/skills/` (Codex) and `.claude/skills/`
-(Claude Code); route by frontmatter `description`. Near-universal:
-`mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`.
+Use `.agents/skills/` (Codex) and `.claude/skills/` (Claude); route by frontmatter
+`description`. Common: `mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`.
 
 ## Codex Governor
 

examples/generated-agent-entrypoints/mq-hal/AGENTS.md

@@ -44,31 +44,27 @@ Stop reading as soon as the task is grounded.
 
 - Prefer task packs and agent views over full notes.
 - Prefer hot/index over pattern notes.
-- Do not scan the whole vault by default.
-- Do not open multiple pattern notes unless clearly needed.
-- Summarize instead of replaying long note bodies.
+- Do not scan the whole vault or several pattern notes by default.
+- Summarize instead of replaying note bodies.
 
 ## Rules
 
 - Do not duplicate logic owned by another MQ repo.
 - Prefer JSON contracts over free-text coupling.
-- Keep repo boundaries explicit.
-- Use `mqobsidian` only as durable memory, not runtime truth.
-- Verify current code behavior, tests, contracts, and CLI behavior in this repo.
+- Keep repo boundaries explicit; use `mqobsidian` as memory, not runtime truth.
+- Verify current code, tests, contracts, and CLI behavior in this repo.
 
 ## Durable Memory
 
-MQ-stack memory lives in `mqobsidian`. Use generated context packs before
-reading large docs.
+MQ-stack memory lives in `mqobsidian`; use context packs before large docs.
 
 `mqobsidian` is durable memory, not live runtime truth. If the task depends on
 current code behavior, tests, contracts, CLI behavior, or runtime state, verify
 in this repo before making claims.
 
 ## Observation Emission
 
-After evidence-backed work reveals a reusable pattern, workflow, convention, or
-review finding, emit one observation:
+After evidence-backed work reveals a reusable pattern or finding, emit one observation:
 
 ```bash
 uv --directory ${MQ_OBSIDIAN_DIR:-$HOME/mqobsidian}/memory run python commands/emit_observation.py \
@@ -83,19 +79,24 @@ Do not emit secrets, private paths, raw logs, chain-of-thought, or unevidenced o
 
 ## Source Intelligence
 
-If `.codegraph/` exists, prefer CodeGraph for source-structure questions before
-broad file scans: symbol lookup, callers/callees, impact analysis, code-flow.
+If `.codegraph/` exists, use CodeGraph MCP before broad scans:
+`codegraph_context` first; use trace/explore/impact as the task requires.
+Treat returned source as read; use targeted reads only for missing, stale, or
+unsupported detail. Use `mqobsidian` for durable memory and repo boundaries.
 
-Do not use CodeGraph as durable MQ memory. Use `mqobsidian` context packs and
-cards for memory, repo boundaries, and prior verified work.
+## MQ Model Routing
+
+Before a non-trivial change, call `mq_route_inspect`; for cross-repo work also
+call `mq_context_pack`. Treat `mq_route_shadow` only as advisory evidence.
+Codex or Claude stays authoritative for medium/high-risk work. Verify against
+repo code/tests and escalate when the router reports an escalation condition.
 
 ## Writing Rules
 
 When creating notes, summaries, or exports:
 
 - separate facts, interpretation, and recommendation
-- keep outputs compact
-- preserve timestamps and provenance when relevant
+- keep outputs compact; preserve timestamps and provenance when relevant
 - prefer links over duplicated prose
 - avoid raw dumps
 
@@ -104,9 +105,8 @@ or machine-specific private paths.
 
 ## MQ Skills
 
-Use repo-local skills from `.agents/skills/` (Codex) and `.claude/skills/`
-(Claude Code); route by frontmatter `description`. Near-universal:
-`mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`.
+Use `.agents/skills/` (Codex) and `.claude/skills/` (Claude); route by frontmatter
+`description`. Common: `mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`.
 
 ## Codex Governor